沐曦通用 GPU 与 MXMACA® 软件栈
AI 推理用户手册
OG‑23025‑020‑F5_V20 2026‑05‑08

声明
版权所有 ©2023‑2026 沐曦集成电路（上海）股份有限公司。保留所有权利。
本文档中呈现的信息属于沐曦集成电路（上海）股份有限公司和/或其附属公司（以下统称为“沐曦股
份” ） ，非经沐曦股份事先书面许可，任何实体或个人均不得获得本文档的副本，且无权以任何方式处理
本文档，包括但不限于使用、复制、修改、合并、出版、发行、销售或传播本文档的部分或全部。
本文档内容仅供参考，不提供任何形式的、明示或暗示的保证，包括但不限于对适销性、适用于任何目
的和/或不侵权的保证。在任何情况下，沐曦股份均不对因本文档引起的、由本文档造成的、或与之相关
的任何索赔、损害或其他责任负责。
沐曦股份保留自行决定随时更改、修改、添加或删除本文档的部分或全部的权利。沐曦股份保留最终解
释权。
沐曦、MetaX 和其他沐曦图标是沐曦股份的商标。本文档中提及的所有其他商标和商品名称均为其各自
所有者的财产。
AI 推理用户手册
目录
1 概述 1
1.1 MacaRT 介绍 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 MacaRT 功能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3 适用产品 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2 环境依赖及 MacaRT 安装 3
2.1 环境依赖 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 安装 MacaRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2.1 MacaRT C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2.2 MacaRT Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.3 使用 MacaRT 容器镜像 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3 MacaRT C++ API 5
3.1 部署 ONNX 模型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.1 创建 Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.2 获取模型图的输入输出信息 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.3 构建模型输入 Tensors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1.4 获取模型输出 Tensors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2 绑定输入输出设备 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.1 绑定输入输出数据到可分页内存上 . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.2 绑定输入输出数据到固页内存上 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.3 绑定输入输出数据到显存上 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.3 动态 Batch 推理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.4 提升沐曦通用 GPU 推理性能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.4.1 设备 ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.4.2 MacaRT 显存管理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.5 自定义算子 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.5.1 Domain 的定义 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.5.2 Kernel 输入输出的数据排布 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4 MacaRT Python API 13
4.1 部署 ONNX 模型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.1 创建 Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.2 获取模型图的输入输出信息 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.3 构建模型输入字典 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.4 获取模型输出 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2 绑定输入输出设备 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2.1 绑定输入输出数据到可分页内存上 . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2.2 绑定输入输出数据到固页内存上 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2.3 绑定输入输出数据到显存上 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
OG‑23025‑020‑F5_V20 沐曦股份专有信息 i
AI 推理用户手册
4.3 动态 Batch 推理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.4 提升沐曦通用 GPU 推理性能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.4.1 设备 ID 设置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5 MacaRT 工具链 17
5.1 MacaConverter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.1.1 安装 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.1.2 功能列表 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.1.3 使用说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.1.3.1 Caffe 模型转 ONNX 模型 . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.1.3.2 TensorFlow（H5）模型转 ONNX 模型 . . . . . . . . . . . . . . . . . . . . 20
5.1.3.3 TensorFlow（SavedModel）模型转 ONNX 模型 . . . . . . . . . . . . . . 20
5.1.3.4 TensorFlow（CheckPoint）模型转 ONNX 模型 . . . . . . . . . . . . . . 20
5.1.3.5 TensorFlow（pb）模型转 ONNX 模型 . . . . . . . . . . . . . . . . . . . . 21
5.1.3.6 PyTorch 模型转 ONNX 模型（输入包含模型定义和权重） . . . . . . . . . 21
5.1.3.7 PyTorch 模型转 ONNX 模型（输入仅包含权重） . . . . . . . . . . . . . . 22
5.1.3.8 PyTorch 模型转 ONNX 模型 （输入仅包含权重， 且模型定义在 Torchvision
中） . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.1.3.9 Darknet 模型转 ONNX 模型 . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.1.3.10 PaddlePaddle 模型转 ONNX 模型（输入包含权重和定义） . . . . . . . . 23
5.1.3.11 PaddlePaddle 模型转 ONNX 模型（输入仅包含权重） . . . . . . . . . . . 23
5.1.3.12 PaddlePaddle 模 型 转 ONNX 模 型 （输 入 仅 包 含 权 重， 模 型 在 pad‑
dle.vision 中定义） . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.1.3.13 动态 Batch 转换 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.1.3.14 ONNX 简化 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.1.3.15 FP32 转 FP16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.1.3.16 子图提取 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.1.3.17 op_set 版本转换 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.1.3.18 Pad 融合 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.1.3.19 Float32 转 Uint8（仅针对模型的 input 数据，非所有算子） . . . . . . . 26
5.1.3.20 MatMul+Add 融合为 Gemm . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.1.3.21 MHA 融合 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.2 MacaPrecision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.2.1 安装 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.2.2 使用说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.2.2.1 常规模型（FP32/FP16） . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.2.2.2 量化模型（经过 MacaQuantizer 量化后的模型） . . . . . . . . . . . . . . 28
5.3 MacaQuantizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.3.1 安装 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.3.2 使用说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.3.2.1 预处理说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.3.2.2 dataset.txt 文本格式说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.3.3 注意事项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6 MacaRT‑LLM 33
OG‑23025‑020‑F5_V20 沐曦股份专有信息 ii
AI 推理用户手册
6.1 MacaRT‑LLM 介绍 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.2 MacaRT‑LLM 功能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.3 MacaRT‑LLM 使用流程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.3.1 模型转换 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.3.1.1 安装 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.3.1.2 转换为 PMX 模型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.3.1.3 模型切分 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.3.1.4 模型合并（可选） . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.3.1.5 PMX 模型测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.3.1.6 导出为 ONNX 模型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.3.2 本地模型部署精度验证 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
6.3.3 本地模型部署性能测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
6.3.4 服务化部署 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.3.4.1 服务端部署 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.3.4.2 C++ 客户端部署 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
6.3.4.3 Python 客户端部署 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.3.4.4 服务端输出性能数据解析 . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
7 MacaRT‑vLLM 49
7.1 MacaRT‑vLLM 介绍 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.2 MacaRT‑vLLM 功能与局限性 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.3 MacaRT‑vLLM 使用流程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.3.1 环境准备 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.3.1.1 使用 vLLM 镜像 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.3.1.2 安装 wheel 包 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.3.1.3 配置环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.3.2 离线推理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.3.3 吞吐测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
7.3.4 Server 服务 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
8 MacaRT‑vLLM‑metax 53
8.1 MacaRT‑vLLM‑metax 介绍 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
8.1.1 分支说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
8.2 MacaRT‑vLLM‑metax 功能与局限性 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
8.3 MacaRT‑vLLM‑metax 使用流程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
8.3.1 环境准备 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
8.3.1.1 使用 vLLM 镜像 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
8.3.1.2 安装 wheel 包 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
8.3.1.3 源代码构建教程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
8.3.1.4 设置环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
8.3.1.5 构建 vLLM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
8.3.1.6 构建 vLLM‑metax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
8.3.2 离线推理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
8.3.3 吞吐测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
8.3.4 Server 服务 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
OG‑23025‑020‑F5_V20 沐曦股份专有信息 iii
AI 推理用户手册
9 MacaRT‑ModelZoo 59
9.1 MacaRT‑ModelZoo 介绍 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
9.2 模型评测条件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
9.3 代码目录结构及说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
9.4 源码、模型和数据集 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
9.4.1 源码镜像获取 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
9.4.2 模型获取 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
9.4.3 数据集获取 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
9.5 模型评测步骤 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
9.5.1 启动容器镜像 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
9.5.2 建立数据集的关联 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
9.5.3 执行模型评测 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
10 MacaRT‑LMDeploy 63
10.1 MacaRT‑LMDeploy 介绍 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
10.2 MacaRT‑LMDeploy 功能与局限性 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
10.3 MacaRT‑LMDeploy 使用流程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
10.3.1 环境准备 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
10.3.1.1 获取 vLLM 镜像 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
10.3.1.2 安装 dlinfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
10.3.1.3 安装 LMDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
10.3.2 离线推理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
10.3.3 静态推理性能测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
10.3.4 Server 服务动态推理性能测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
11 Diffusers 68
12 Transformers 69
13 MacaRT‑SGLang 70
13.1 MacaRT‑SGLang 介绍 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
13.2 MacaRT‑SGLang 功能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
13.3 MacaRT‑SGLang 使用流程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
13.3.1 环境准备 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
13.3.1.1 使用 SGLang 镜像 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
13.3.1.2 设置环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
13.3.1.3 启动 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
13.3.2 在线推理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
13.3.3 吞吐测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
13.3.4 精度测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
13.3.4.1 MMLU 精度测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
13.3.4.2 C‑Eval 精度测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
14 附录 74
14.1 术语/缩略语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
OG‑23025‑020‑F5_V20 沐曦股份专有信息 iv
AI 推理用户手册
图目录
图 1.1 MacaRT 的模型推理整体架构 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
图 3.1 动态 Batch 推理原理图 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
图 5.1 MacaRT 模型部署工具链 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
图 5.2 预处理流程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
图 6.1 OpenPPL‑LLM 大模型推理流程图 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
图 6.2 C++ 客户端目录结构图 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
图 6.3 Python 客户端目录结构图 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
图 6.4 服务端输出性能数据示例（llama‑7b） . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
OG‑23025‑020‑F5_V20 沐曦股份专有信息 v
AI 推理用户手册
表目录
表 3.1 OrtMACAProviderOptions 支持的配置选项 . . . . . . . . . . . . . . . . . . . . . . . . . . 10
表 5.1 支持的模型转换类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
表 5.2 扩展功能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
表 5.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
表 5.4 MacaQuantizer 支持的 ONNX 算子 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
表 6.1 MacaPMX 支持的大模型及对应转换函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
表 6.2 MacaPMX 支持的大模型及对应 PMX 切分函数 . . . . . . . . . . . . . . . . . . . . . . . . . 36
表 6.3 MacaPMX 支持的大模型及对应 PMX 合并函数 . . . . . . . . . . . . . . . . . . . . . . . . . 36
表 6.4 MacaPMX 支持的大模型及对应 PMX 模型运行函数 . . . . . . . . . . . . . . . . . . . . . . 37
表 6.5 MacaPMX 支持的大模型及对应 ONNX 导出函数 . . . . . . . . . . . . . . . . . . . . . . . . 39
表 7.1 vLLM 与 PyTorch 的版本兼容关系 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
表 8.1 vLLM‑metax、vLLM 官方、PyTorch 的版本映射关系 . . . . . . . . . . . . . . . . . . . . . 53
表 9.1 模型评测命令行参数解析 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
OG‑23025‑020‑F5_V20 沐曦股份专有信息 vi
AI 推理用户手册
更新记录
版本 日期 更新说明
V20 2026‑05‑08 更新以下章节：
7.3.1.1 使用 vLLM 镜像
8.1 MacaRT‑vLLM‑metax 介绍
8.3.1.1 使用 vLLM 镜像
V19 2026‑03‑27 更新文档适用范围
V18 2025‑12‑15 新增以下章节：
8 MacaRT‑vLLM‑metax
V17 2025‑10‑09 更新以下章节：
6.3.1.1 安装
7.3.1.2 安装 wheel 包
9.4.1 源码镜像获取
V16 2025‑07‑04 更新以下章节：
5.1.2 功能列表
新增以下章节：
5.1.3.20 MatMul+Add 融合为 Gemm
5.1.3.21 MHA 融合
V15 2025‑06‑04 新增以下章节：
13 MacaRT‑SGLang
V14 2025‑04‑28 更新以下章节：
2.2.2 MacaRT Python
5.1.1 安装
5.2.1 安装
5.3.1 安装
7.1 MacaRT‑vLLM 介绍
7.2 MacaRT‑vLLM 功能与局限性
7.3.1.2 安装 wheel 包
7.3.2 离线推理
7.3.3 吞吐测试
7.3.4 Server 服务
新增以下章节：
11 Diffusers
12 Transformers
V13 2025‑03‑28 更新以下章节：
7.1 MacaRT‑vLLM 介绍
10.3.1.2 安装 dlinfer
新增以下章节：
7.3.1.3 配置环境变量
下页继续
OG‑23025‑020‑F5_V20 沐曦股份专有信息 vii
AI 推理用户手册
表 1 – 续上页
版本 日期 更新说明
V12 2025‑02‑27 更新以下章节：
10.3.1.2 安装 dlinfer
10.3.1.3 安装 LMDeploy
V11 2024‑12‑27 更新以下章节：
7 MacaRT‑vLLM
新增以下章节：
10 MacaRT‑LMDeploy
V10 2024‑11‑15 更新以下章节：
7 MacaRT‑vLLM
新增以下章节：
9 MacaRT‑ModelZoo
V09 2024‑09‑18 更新以下章节：
2.3 使用 MacaRT 容器镜像
V08 2024‑08‑05 新增以下章节：
3.5 自定义算子
V07 2024‑06‑14 新增以下章节：
7 MacaRT‑vLLM
V06 2024‑05‑15 更新以下章节：
6.3.1.2 转换为 PMX 模型
6.3.1.3 模型切分
6.3.1.4 模型合并（可选）
6.3.1.5 PMX 模型测试
6.3.1.6 导出为 ONNX 模型
V05 2024‑03‑15 新增曦云 ® 系列 GPU 产品信息
更新以下章节：
6.3.2 本地模型部署精度验证
6.3.4.1 服务端部署
V04 2024‑02‑29 更新以下章节：
6.3.2 本地模型部署精度验证
V03 2024‑01‑31 更新以下章节：
6.3.1.2 转换为 PMX 模型
6.3.1.5 PMX 模型测试
6.3.1.6 导出为 ONNX 模型
下页继续
OG‑23025‑020‑F5_V20 沐曦股份专有信息 viii
AI 推理用户手册
表 1 – 续上页
版本 日期 更新说明
V02 2023‑12‑29 更新以下章节：
2.2.2 MacaRT Python
3.4.2 MacaRT 显存管理
5.1.1 安装
5.2.1 安装
新增以下章节：
6 MacaRT‑LLM
V01 2023‑10‑16 首次发布
OG‑23025‑020‑F5_V20 沐曦股份专有信息 ix
AI 推理用户手册
1 概述
本文档主要用于指导用户如何使用 MacaRT 推理引擎，并快速有效地将训练好的模型部署到沐曦通用
GPU 上。
1.1 MacaRT 介绍
MacaRT （MXMACA® Runtime） 是在沐曦通用 GPU 上进行人工智能算法模型部署和执行的推理引擎， 它
是在 ONNX Runtime 上扩展了 MXMACA 后端。在进行推理时，只需指定 MXMACA Execution Provider
（MacaEP）就可以在沐曦通用 GPU 上完成模型推理。MacaRT 的使用方法与 ONNX Runtime 完全兼容。
MacaRT 进行模型推理的整体架构，如图 1.1 所示，可以分为以下部分：
• 解析 ONNX 模型，获取模型图和参数信息
• 对模型图进行处理，包括图优化、图拆分、图编译等
• 通过 MacaEP 在沐曦通用 GPU 上执行模型
图 1.1 MacaRT 的模型推理整体架构
1 概述 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 1
AI 推理用户手册
1.2 MacaRT 功能
MacaRT 包含了以下的功能和特性：
• MacaRT 提供了 C++ 和 Python 接口
• 支持多种模型数据类型，包括 float32、float16、int8、uint8 等
• 支持动态 Batch 推理
• 支持多线程调用和多进程调用
• 支持模型图优化、模型量化等特性
• MacaRT 工具链，包括 MacaConverter、MacaPrecision、MacaQuantizer
1.3 适用产品
本文档适用于沐曦 MXC500 系列产品：曦云 ® C500、C500X、C550、C550‑PL、C588，曦思® N260，曦
索 ® X206；以及 MXC600 系列产品：曦云 ® C600，曦思 ® N300，曦索 ® X301、X302。
1 概述 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 2
AI 推理用户手册
2 环境依赖及 MacaRT 安装
2.1 环境依赖
在使用 MacaRT 之前，必须确保服务器已安装沐曦通用 GPU 板卡及其驱动程序。
2.2 安装 MacaRT
操作步骤
1. 执行以下命令，快速安装 MacaRT 的 deb 软件安装包。deb 软件安装包可以在相应 GPU 的软件发布
包中找到。
dpkg -i onnxruntime-maca_*.deb
安装结束后，MacaRT 相关文件均会安装到/opt/maca‑ai/onnxruntime‑maca 目录中。
2.2.1 MacaRT C++
操作步骤
1. 执行以下命令，快速验证是否已正确安装 MacaRT C++ 库。
/opt/maca-ai/onnxruntime-maca/bin/maca_test --model_dir /opt/maca-ai/onnxruntime-
,→maca/sample/test_add --check_mode 1
对获取到的 test_add 中模型在 CpuEP 和 MacaEP 上执行的结果进行对比，若对比结果相同则代表
正确安装了 MacaRT。
2.2.2 MacaRT Python
MacaRT Python 版本的 wheel 安装包可在/opt/maca‑ai/onnxruntime‑maca/python 中发现。 在安
装 wheel 包之前，须确保当前 Python 版本和 wheel 包上标识的 Python 版本一致。当前为 Python 3.8
及 Python 3.10。
操作步骤
1. 执行以下命令，安装 MacaRT Python 版本 wheel 包：onnxruntime_gpu‑1.12.0+mc*.whl。
pip install /opt/maca-ai/onnxruntime-maca/python/onnxruntime_gpu-1.12.0+mc*.whl
2. 执行以下命令，快速验证是否已正确安装 MacaRT。
2 环境依赖及 MacaRT 安装 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 3
AI 推理用户手册
python /opt/maca-ai/onnxruntime-maca/sample/python/maca_test.py -m /opt/maca-ai/
,→onnxruntime-maca/sample/test_add
注解: MacaRT Python 主要依赖 numpy、protobuf 等，在使用 pip 进行安装时会自动安装
MacaRT Python 的依赖包。
2.3 使用 MacaRT 容器镜像
从发布的软件包中获取 onnxruntime 容器镜像并启动。onnxruntime 容器镜像包含 MacaRT 及工具
链。容器镜像的使用，参见《沐曦通用 GPU 用户指南》中“容器相关场景支持”章节。
2 环境依赖及 MacaRT 安装 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 4
AI 推理用户手册
3 MacaRT C++ API
3.1 部署 ONNX 模型
MacaRT 支持使用 C++ API 将 ONNX 模型部署到沐曦通用 GPU 上，并完成推理。
3.1.1 创建 Session
操作步骤
1. 配置日志对象 Ort::Env。
#include <onnxruntime_cxx_api.h>
std::string ep_name = "MacaEP";
Ort::Env env(OrtLoggingLevel::ORT_LOGGING_LEVEL_INFO, ep_name.c_str());
2. 在 SessionOption 中添加 MacaEP 的信息。
OrtMACAProviderOptions maca_options;
maca_options.device_id=0;
Ort::SessionOptions sessionOptions;
sessionOptions.AppendExecutionProvider_MACA(maca_options);
注解:
• SessionOption 用于在创建 Session 时，指定 MacaRT 所使用的 EP 信息。
• SessionOption 的详细信息，可参考ONNX Runtime 相关文档。
3. 创建 Session 对象。
Ort::Session session(env, your_onnx_model_path, sessionOptions);
3.1.2 获取模型图的输入输出信息
操作步骤
1. 执行以下命令，获取模型图的输入输出信息。
Ort::AllocatorWithDefaultOptions allocator;
std::vector<const char*> inputNames, outputNames;
for ( size_t i=0; i< session.GetInputCount(); i++){
inputNames.push_back(session.GetInputName(i , allocator));
(下页继续)
3 MacaRT C++ API 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 5
AI 推理用户手册
(续上页)
}
for ( size_t i=0; i< session.GetOutputCount(); i++){
outputNames.push_back(session.GetOutputName(i , allocator));
}
3.1.3 构建模型输入 Tensors
操作步骤
1. 准备输入数据。假设提供的模型输入数据和数据长度是通过以下变量名称提供，并且输入数据处于
可分页内存上。
void* input_data[inputNames.size()]; // input data ptr
size_t input_data_len[inputNames.size()]; // input data len
2. 创建 MemoryInfo，用于标识输入数据所在的设备信息。
Ort::MemoryInfo memoryInfo = 
,→Ort::MemoryInfo::CreateCpu(OrtAllocatorType::OrtArenaAllocator,
,→OrtMemType::OrtMemTypeDefault);
3. 创建输入 Tensors。假设模型的输入形状是固定的。
std::vector<Ort::Value> inputTensors;
for(size_t i=0; i<inputNames.size(); i++){
// get input node data type
Ort::TypeInfo inputTypeInfo = session.GetInputTypeInfo(i);
auto inputTensorInfo = inputTypeInfo.GetTensorTypeAndShapeInfo();
ONNXTensorElementDataType inputType = inputTensorInfo.GetElementType();
// get input node data length
std::vector<int64_t> inputDims=inputTensorInfo.GetShape();
inputTensors.push_back(Ort::Value::CreateTensor(memoryInfo,input_data[i],
,→input_data_len[i],inputDims.data(),inputDims.size(),inputType));
}
3.1.4 获取模型输出 Tensors
操作步骤
1. 执行以下命令，通过同步执行的方式，获取模型的输出 Tensors。在不指定设备信息的情况下，输出
Tensors 中的数据默认位于可分页内存上。
auto ouput = session.Run(Ort::RunOptions{nullptr},inputNames.data(), 
,→inputTensors.data(),inputNames.size(), ouputNames.data(), outputNames.size());
mcStreamSynchronize(stream);
3 MacaRT C++ API 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 6
AI 推理用户手册
3.2 绑定输入输出设备
有多个模型且模型间存在数据拷贝时，绑定输入输出内存信息，可帮助减少模型之间不必要的输入输出
数据拷贝。MacaRT 支持将模型的输入或输出绑定到：
• 两种 Host 端的内存页面：可分页内存（Pageable Memory）和固页内存（Pinned Memory）
• 一种 Device 端的内存信息：沐曦通用 GPU 显存（Video Memory）
推荐使用固页内存存储模型输入输出数据，可以提高数据传输效率。
3.2.1 绑定输入输出数据到可分页内存上
具体操作步骤，参见 3.1 部署 ONNX 模型。
3.2.2 绑定输入输出数据到固页内存上
操作步骤
1. 准备输入数据。假设提供的模型输入数据和数据长度是通过以下变量名称提供，并且输入数据处于
固页内存上。
void* input_data[inputNames.size()]; // input data ptr
size_t input_data_len[inputNames.size()]; // input data len
2. 创建 MemoryInfo，用于标识输入数据所在的设备信息。
constexpr const char* MACA_PINNED_STR= "MacaPinned";
Ort:MemoryInfo memoryInfo = Ort::MemoryInfo(MACA_PINNED_STR, 
,→OrtAllocatorType::OrtDeviceAllocator,0, OrtMemType::OrtMemTypeCPUOutput);
3. 创建输入 Tensors。假设模型的输入形状是固定的。
std::vector<Ort::Value> inputTensors;
for(size_t i=0; i<inputNames.size(); i++){
// get input node data type
Ort::TypeInfo inputTypeInfo = session.GetInputTypeInfo(i);
auto inputTensorInfo = inputTypeInfo.GetTensorTypeAndShapeInfo();
ONNXTensorElementDataType inputType = inputTensorInfo.GetElementType();
// get input node data length
std::vector<int64_t> inputDims=inputTensorInfo.GetShape();
inputTensors.push_back(Ort::Value::CreateTensor(memoryInfo,input_data[i],
,→input_data_len[i],inputDims.data(),inputDims.size(),inputType));
}
4. 执行以下命令，使用 IOBinding 来获取模型输出。
3 MacaRT C++ API 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 7
AI 推理用户手册
Ort::IoBinding ioBinding(session);
for(size_t i=0; i< inputNames.size(), i++){
ioBinding.BindInput(inputNames[i],inputTensors[i]);
}
for(size_t i=0; i< outputNames.size(), i++){
ioBinding.BindOutput(outputNames[i],memoryInfo);
}
session.Run(Ort::RunOptions{nullptr},ioBinding);
auto outputs=ioBinding.GetOutputValues();
3.2.3 绑定输入输出数据到显存上
操作步骤
1. 准备输入数据。假设提供的模型输入数据和数据长度是通过以下变量名称提供，并且输入数据处于
沐曦通用 GPU 显存上。
void* input_batch_data[inputNames.size()]; // input data ptr
size_t input_batch_data_len[inputNames.size()]; // input data len
2. 创建 MemoryInfo，用于标识输入数据所在的内存信息。
constexpr const char* MACA_STR= "Maca";
Ort:MemoryInfo memoryInfo = Ort::MemoryInfo(MACA_STR, 
,→OrtAllocatorType::OrtDeviceAllocator, gpu_id, OrtMemType::OrtMemTypeDefault);
3. 创建输入 Tensors。假设模型的输入形状是固定的。
std::vector<Ort::Value> inputTensors;
for(size_t i=0; i<inputNames.size(); i++){
// get input node data type
Ort::TypeInfo inputTypeInfo = session.GetInputTypeInfo(i);
auto inputTensorInfo = inputTypeInfo.GetTensorTypeAndShapeInfo();
ONNXTensorElementDataType inputType = inputTensorInfo.GetElementType();
// get input node data length
std::vector<int64_t> inputDims=inputTensorInfo.GetShape();
inputTensors.push_back(Ort::Value::CreateTensor(memoryInfo,input_data[i], 
,→input_data_len[i], inputDims.data(), inputDims.size(),inputType));
}
4. 执行以下命令，使用 IOBinding 来获取模型输出。
Ort::IoBinding ioBinding(session);
for(size_t i=0; i< inputNames.size(), i++){
ioBinding.BindInput(inputNames[i],inputTensors[i]);
}
for(size_t i=0; i< outputNames.size(), i++){
(下页继续)
3 MacaRT C++ API 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 8
AI 推理用户手册
(续上页)
ioBinding.BindOutput(outputNames[i],memoryInfo);
}
session.Run(Ort::RunOptions{nullptr},ioBinding);
auto outputs=ioBinding.GetOutputValues();
3.3 动态 Batch 推理
MacaRT 支持 ONNX Runtime 的动态 Batch 推理功能， 在指定推理后端为 MacaEP 时， 使用BatchSize
值为‑1 的模型。
推理原理
推理原理如图 3.1 所示，其中 input_i_j 代表第 i 组 Batch 数据，模型的第 j 个输入，M 为模型结构需要
的输入个数，N 为输入的 Batch 数目，K 为模型结构的输出个数。input_i 包含了 input_0_i 到 input_
N_i 的所有输入数据。
图 3.1 动态 Batch 推理原理图
操作步骤
1. 准备输入数据。假设提供的模型输入数据和数据长度是通过以下变量名称提供，input_data 包含了
Batch 为 N 的输入数据，且输入数据位于可分页内存上。
void* input_data[inputNames.size()];
size_t input_data_len[inputNames.size()];
2. 创建 MemoryInfo，用于标识输入数据所在的设备信息。
Ort::MemoryInfo memoryInfo =Ort::MemoryInfo::CreateCpu(
OrtAllocatorType::OrtArenaAllocator, OrtMemType::OrtMemTypeDefault);
3. 创建输入 Tensors。
std::vector<Ort::Value> inputTensors;
for(size_t i=0; i<inputNames.size(); i++){
// get input node data type
(下页继续)
3 MacaRT C++ API 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 9
AI 推理用户手册
(续上页)
Ort::TypeInfo inputTypeInfo = session.GetInputTypeInfo(i);
auto inputTensorInfo = inputTypeInfo.GetTensorTypeAndShapeInfo();
ONNXTensorElementDataType inputType = inputTensorInfo.GetElementType();
// get input node data length
std::vector<int64_t> inputDims=inputTensorInfo.GetShape();
inputDims[0]=N;
inputTensors.push_back(Ort::Value::CreateTensor(memoryInfo,input_data[i], 
,→input_data_len[i], inputDims.data(), inputDims.size(),inputType));
}
4. 支持使用以下两种方式获取模型输出。
// session run
auto ouput = session.Run(Ort::RunOptions{nullptr},inputNames.data(),
inputTensors.data(),inputNames.size(),
ouputNames.data(),outputNames.size());
或
// iobinding
Ort::IoBinding ioBinding(session);
for(size_t i=0; i< inputNames.size(), i++){
ioBinding.BindInput(inputNames[i],inputTensors[i]);
}
for(size_t i=0; i< outputNames.size(), i++){
ioBinding.BindOutput(outputNames[i],memoryInfo);
}
session.Run(Ort::RunOptions{nullptr},ioBinding);
auto outputs = ioBinding.GetOutputValues();
3.4 提升沐曦通用 GPU 推理性能
使用 MacaRT 将 ONNX 模型部署到沐曦通用 GPU 上时， MacaEP 配置信息OrtMACAProviderOptions
会直接影响 MacaRT 的推理速度。OrtMACAProviderOptions 支持的配置选项参见表 3.1。
表 3.1 OrtMACAProviderOptions 支持的配置选项
选项 说明
device_id 配置所使用的设备号
gpu_mem_limit MacaRT 使用的最大显存量
arena_extend_strategy 显存增长策略
default_memory_arena_cfg 内存管理配置
3 MacaRT C++ API 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 10
AI 推理用户手册
3.4.1 设备 ID
当有多个 GPU 时， 需通过配置gpu_id 来管理。 通过在OrtMACAProviderOptions 中配置 device_
id，可以指定所使用的 gpu_id，默认为 0。
OrtMACAProviderOptions maca_options;
maca_options.device_id = your_gpu_id;
3.4.2 MacaRT 显存管理
MacaRT 提供 BFCarena 显存管理策略，可以有效地使用显存，避免显存重复申请和显存碎片。有关
BFCarena 的更多信息，可参考ONNX Runtime 相关文档。
有以下两种方法可以配置 MacaEP 显存管理策略：
• 直接使用 OrtMACAProviderOptions 配置。
OrtMACAProviderOptions maca_options;
maca_options.gpu_mem_limit=SIZE_MAX;
maca_options.arena_extend_strategy=0;
• 创建一个 OrtArenaCfg 对象。
auto cfg = Ort::ArenaCfg(SIZE_MAX,0,-1,-1);
OrtMACAProviderOptions maca_options;
maca_options.default_memory_arena_cfg=cfg.release();
3.5 自定义算子
MacaRT 支持用户定义非官方的 ONNX 算子进行推理。
操作步骤
1. 使用 C++ 的 API 构建自定义算子库。
2. 通过使用 C++ API 或 Python API 将自定义算子库注册到 SessionOptions 对应的 MacaEP。
3. 加载包含自定义算子的模型进行推理。
上述步骤的具体实现细节，可以参考 ONNX Runtime 官方文档中关于 Cuda EP 自定义算子的实现步骤，
MacaEP 保持基本一致。 也在/opt/maca‑ai/onnxruntime‑maca/custom_op_test中提供了完整的
实现样例。
以下介绍 MacaEP 自定义算子的不同之处。
3 MacaRT C++ API 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 11
AI 推理用户手册
3.5.1 Domain 的定义
将自定义算子注册到 MacaEP 的后端时，Domain 必须设置为 custom.op，即：
static const char* c_OpDomain="custom.op";
3.5.2 Kernel 输入输出的数据排布
在构建自定义算子库时，在 MacaRT 中新增接口用于指定 Kernel 需要的输入输出数据排布。
OrtDataLayout GetInputDataLayout(size_t index); // 指 定 输 入 的 数 据 排 布
OrtDataLayout GetOutputDataLayout(size_t index); // 指 定 输 出 的 数 据 排 布
当前 MacaEP 的自定义算子支持以下三种数据排布：
typedef enum OrtDataLayout{
NCHW,
NHWC8,
NHWC16,
}OrtDataLayout;
需要注意的是：
• 在默认情况下，所有自定义算子 Kernel 的输入输出都是 NCHW 格式。
• 模型的输入数据排布必须是 NCHW 格式，MacaEP 会根据 Kernel 需求自动进行数据排布的转换。
• 模型的输出会被 MacaEP 自动转换为 NCHW 格式的排布。
3 MacaRT C++ API 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 12
AI 推理用户手册
4 MacaRT Python API
4.1 部署 ONNX 模型
MacaRT 支持使用 Python API 将 ONNX 模型部署到沐曦通用 GPU 上，并完成推理。
4.1.1 创建 Session
操作步骤
1. 执行以下命令，创建 Session。
import onnxruntime as ort
provider_options=[{'device_id':0}]
session = ort.InferenceSession(your_onnx_model_path, providers=[
,→"MACAExecutionProvider"],provider_options=provider_options)
4.1.2 获取模型图的输入输出信息
操作步骤
1. 执行以下命令，获取模型图的输入输出信息。
input_nodes = session.get_inputs()
input_names = [i_n.name for i_n in input_nodes]
output_nodes = session.get_outputs()
output_names = [o_n.name for o_n in output_nodes]
4.1.3 构建模型输入字典
操作步骤
1. 准备输入数据。假设已创建一个包含所有模型输入数据的 List，List 中的元素为模型的每个输入的
numpy 数据，且输入 List 的变量名为 input_data_list。
2. 构建输入字典。
input_dict ={}
for i_d, i_n in zip(input_data_list, input_names):
input_dict[i_n] = i_d
4 MacaRT Python API 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 13
AI 推理用户手册
4.1.4 获取模型输出
操作步骤
1. 执行以下命令，获取模型输出。
output_data = session.run([], input_dict )
4.2 绑定输入输出设备
有多个模型且模型间存在数据拷贝时，绑定输入输出内存信息，可帮助减少模型之间不必要的输入输出
数据拷贝。
MacaRT Python API 也支持将模型的输入或输出绑定到可分页内存、固页内存和显存上。
4.2.1 绑定输入输出数据到可分页内存上
操作步骤
1. 操作步骤同 4.1.1 创建 Session。
2. 操作步骤同 4.1.2 获取模型图的输入输出信息。
3. 操作步骤同 4.1.3 构建模型输入字典。
4. 执行以下命令，使用 IOBinding 获取模型输出。
io_binding = session.io_binding()
for key in input_dict.keys():
io_binding.bind_ortvalue_input(key,ort.OrtValue.ortvalue_from_numpy(input_
,→dict[key], "cpu",0))
for o_n in output_names:
io_binding.bind_output(o_n,"cpu")
session.run_with_iobinding(io_binding)
output = io_binding.get_outputs()
4.2.2 绑定输入输出数据到固页内存上
操作步骤
1. 操作步骤同 4.1.1 创建 Session。
2. 操作步骤同 4.1.2 获取模型图的输入输出信息。
3. 操作步骤同 4.1.3 构建模型输入字典。
4. 执行以下命令，使用 IOBinding 获取模型输出。
4 MacaRT Python API 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 14
AI 推理用户手册
io_binding = session.io_binding()
for key in input_dict.keys():
io_binding.bind_ortvalue_input(key,ort.OrtValue.ortvalue_from_numpy(input_
,→dict[key], "maca_pinned",gpu_id))
for o_n in ouput_names:
io_binding.bind_output(o_n,"maca_pinned")
session.run_with_iobinding(io_binding)
output = io_binding.get_outputs()
4.2.3 绑定输入输出数据到显存上
操作步骤
1. 操作步骤同 4.1.1 创建 Session。
2. 操作步骤同 4.1.2 获取模型图的输入输出信息。
3. 操作步骤同 4.1.3 构建模型输入字典。
4. 执行以下命令，使用 IOBinding 获取模型输出。
io_binding = session.io_binding()
for key in input_dict.keys():
io_binding.bind_ortvalue_input(key,ort.OrtValue.ortvalue_from_numpy(input_
,→dict[key], "maca",gpu_id))
for o_n in output_names:
io_binding.bind_output(o_n,"maca",device_id = gpu_id)
session.run_with_iobinding(io_binding)
output = io_binding.get_outputs()
4.3 动态 Batch 推理
操作步骤
1. 准备输入数据。如下所示，其中 input_* 代表由模型图的其中一个输入，且每一个输入数据的
BatchSize 都为 N。
input_data = [input_0,input_1,...,input_N]
2. 操作步骤同 4.1.1 创建 Session。
3. 操作步骤同 4.1.2 获取模型图的输入输出信息。
4. 使用 IOBinding 获取输出。
io_binding = session.io_binding()
for i_n,b_d in zip(input_names,input_data):
io_binding.bind_ortvalue_input(i_n,ort.OrtValue.ortvalue_from_numpy(b_d, "cpu
(下页继续)
4 MacaRT Python API 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 15
AI 推理用户手册
(续上页)
,→",0))
for o_n in ouput_names:
io_binding.bind_output(o_n,"cpu")
session.run_with_iobinding(io_binding)
output = io_binding.get_outputs()
4.4 提升沐曦通用 GPU 推理性能
使用 MacaRT 将 ONNX 模型部署到沐曦通用 GPU 上时，MacaEP 的配置信息 provider_options 会
直接影响 MacaRT 的推理速度。相关配置信息的介绍，参见 3.4 提升沐曦通用 GPU 推理性能。
4.4.1 设备 ID 设置
操作步骤
1. 执行以下命令，配置 device_id 来指定 gpu_id，以管理多个 GPU。
provider_options=[{'device_id': your_gpu_id }]
4 MacaRT Python API 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 16
AI 推理用户手册
5 MacaRT 工具链
MacaRT 提供以下工具：
• 模型转换工具 MacaConverter。针对各种深度学习框架（如 PyTorch，Caffe，Tensorflow）训练出
来的模型，可以使用 MacaConverter 将训练的模型转换为 ONNX 模型。
• 精度分析工具 MacaPrecision。通过比较 CPU 和沐曦通用 GPU 在各个层的输出值，更好地调试模型。
• 模型量化工具 MacaQuantizer。 相对于 MacaRT 提供的模型量化功能， MacaQuantizer 可以在模型量
化后达到更高的精度和更快的速度。
MacaRT 模型部署工具链如下图所示：
图 5.1 MacaRT 模型部署工具链
5.1 MacaConverter
ONNX 是一种便于在各个主流深度学习框架中迁移模型的中间表达格式，可用于存储训练好的模型。它
使得不同的深度学习框架 （如 PyTorch，Caffe，TensorFlow） 可以采用相同格式存储模型数据，从而进
行推理任务的执行。
为了将不同深度学习框架的模型转换为 ONNX 格式的模型，MacaConverter 的内部封装了常用的开源
转换工具，对外提供统一的转换接口（命令行） ，同时提供了部分算子优化功能。
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 17
AI 推理用户手册
5.1.1 安装
MacaConverter 以 wheel 安 装 包 的 形 式 对 外 发 布， 建 议 在 Conda 环 境 中 安 装 （建 议 Python 版 本
3.10）。 安 装 MacaRT 后， 可 以 在/opt/maca‑ai/onnxruntime‑maca/python/tools 目 录 下 找 到
MacaConverter 对应的 Python 安装包。
操作步骤
1. 执行以下命令，安装 MacaConverter。
conda create -n maca_test python=3.10
source activate maca_test
pip install onnxruntime_gpu-1.12.0+mc*.whl
pip install maca_converter-*.whl
注解: 若运行时报以下错误：
ImportError: libpython3.10.so.1.0: cannot open shared object file: No such 
,→file or directory
可执行以下命令：
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/xxx/anaconda3/envs/maca_test/
,→lib/
wheel 包安装过程中会自动下载相关依赖库，主要有：
• numpy
• onnx
• onnxruntime‑gpu
• TensorFlow==2.4.0
• torch
• torchvision
• onnxoptimizer==0.2.6
• rich==12.0.0
• packaging
• pyyaml
• paddlepaddle
• paddle2onnx
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 18
AI 推理用户手册
5.1.2 功能列表
MacaConverter 支持将多种类型的模型转换为 ONNX 模型，参见表 5.1。
表 5.1 支持的模型转换类型
源模型框架 目标模型框架 说明
Caffe ONNX 支持将 Caffe 模型转换为 ONNX 模型
TensorFlow ONNX 支持将 TensorFlow 模型转换为 ONNX 模型 （包括 CheckPoint，
SavedModel，pb 和 H5 四种格式）
PyTorch ONNX 支持将 PyTorch 模型转换为 ONNX 模型
PaddlePaddle ONNX 支持将 PaddlePaddle 模型转换为 ONNX 模型
Darknet ONNX 支持将 Darknet 模型转换为 ONNX 模型（目前只支持 yolov3
和 yolov4）
MacaConverter 还支持其他功能，参见表 5.2。
表 5.2 扩展功能
功能 说明
动态 batch 转换 支持将 BatchSize 非动态的模型修改为动态 BatchSize
ONNX 优化 支持常规的优化操作（如常量折叠、Conv+BN 融合）
Float32 转 Float16 支持将模型中相关算子的输入类型由 Float32 改为 Float16
子图提取 按照给定的输入/输出提取模型的子图
融合 Pad+Pool 将相邻的 Pad 算子融合进 Pool 算子中
op_set 版本转换 支持将原 ONNX 模型的 op_set 版本转换为目标版本
Float32 转 Uint8 支持将模型的输入类型由 Float32 改为 Uint8（仅针对模型的 input 数
据，非所有算子）
MatMul+Add 融合为 Gemm 支持将模型中的 Matmul+Add 算子转换成 Gemm 算子
MHA 融合 支持将模型中的 KQV 组合融合成 MultiHeadAttentionV1 算子
5.1.3 使用说明
5.1.3.1 Caffe 模型转 ONNX 模型
操作步骤
1. 执行以下命令，将 Caffe 模型转为 ONNX 模型。
python -m maca_converter --model_path ./caffe_model --model_type caffe --output .
,→/output.onnx
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 19
AI 推理用户手册
参数说明：
model_path ：Caffe 模型路径（文件夹，需包含.prototxt 和.caffemodel）
model_type ：模型类型（此处固定为 caffe）
output ：目标模型的路径
5.1.3.2 TensorFlow（H5）模型转 ONNX 模型
操作步骤
1. 执行以下命令，将 TensorFlow H5 格式的模型转为 ONNX 模型。
python -m maca_converter --model_path ./test.h5 --model_type tf-h5 --output ./
,→output.onnx
参数说明：
model_path ：H5 模型路径
model_type ：模型类型（此处固定为 tf‑h5）
output ：目标模型的路径
5.1.3.3 TensorFlow（SavedModel）模型转 ONNX 模型
操作步骤
1. 执行以下命令，将 TensorFlow SavedModel 格式的模型转为 ONNX 模型。
python -m maca_converter --model_path ./tfsm --model_type tf-sm --output ./
,→output.onnx
参数说明：
model_path ：SavedModel 模型路径（文件夹，需包含 assets/saved_model.pb/variables）
model_type ：模型类型（此处固定为 tf‑sm）
output ：目标模型的路径
5.1.3.4 TensorFlow（CheckPoint）模型转 ONNX 模型
操作步骤
1. 执行以下命令，将 TensorFlow CheckPoint 格式的模型转为 ONNX 模型。
python -m maca_converter --model_path ./ckpt/test.meta --model_type tf-ckpt --
,→output ./output.onnx --inputs x:0,y:0 --outputs op_to_store:0 – -inputs_as_
,→nchw x:0,y:0
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 20
AI 推理用户手册
参数说明：
model_path ：CheckPoint 模型路径（文件夹，需包含 checkpoint、.meta、.index、.data 文件，
此参数需指向.meta 文件的路径）
model_type ：模型类型（此处固定为 tf‑ckpt）
output ：目标模型的路径
inputs ：TensorFlow 模型的输入（tensor 变量的名称，一般后面需加:0）
outputs ：TensorFlow 模型的输出（tensor 变量的名称，一般后面需加:0）
inputs_as_nchw ：可选项，如果原始输入维度是 nhwc，可使用此选项转变为 nchw
5.1.3.5 TensorFlow（pb）模型转 ONNX 模型
操作步骤
1. 执行以下命令，将 TensorFlow pb 格式的模型转为 ONNX 模型。
python -m maca_converter --model_path ./test.pb --model_type tf-graph --output ./
,→output.onnx --inputs x:0,y:0 --outputs op_to_store:0 --inputs_as_nchw x:0,y:0
参数说明：
model_path ：pb 模型路径
model_type ：模型类型（此处固定为 tf‑graph）
output ：目标模型的路径
inputs ：TensorFlow 模型的输入（tensor 变量的名称，一般后面需加:0）
outputs ：TensorFlow 模型的输出（tensor 变量的名称，一般后面需加:0）
inputs_as_nchw ：可选项，如果原始输入维度是 nhwc，可使用此选项转变为 nchw
5.1.3.6 PyTorch 模型转 ONNX 模型（输入包含模型定义和权重）
操作步骤
1. 执行以下命令，将 PyTorch 模型转为 ONNX 模型（输入包含模型定义和权重） 。
python -m maca_converter --model_path ./mnist_model.pkl --model_type pytorch --
,→output ./torch.onnx --model_def_file ./CNN.py --model_class_name CNN --input_
,→shape [1,1,28,28]
参数说明：
model_path ：PyTorch 模型路径（模型中包含了权重和定义）
model_type ：模型类型（此处固定为 pytorch）
output ：目标模型的路径
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 21
AI 推理用户手册
model_def_file ：模型定义文件（必须和执行命令的路径在同一目录下）
model_class_name ：模型中定义的类名
input_shape ：模型的输入形状
5.1.3.7 PyTorch 模型转 ONNX 模型（输入仅包含权重）
操作步骤
1. 执行以下命令，将 PyTorch 模型转为 ONNX 模型（输入仅包含权重） 。
python -m maca_converter --model_path ./xxx --model_type pytorch --output ./unet.
,→onnx --model_def_file ./unet.py --model_class_name Net --model_weights_file ./
,→9_epoch_0.56322173.pth --input_shape [64,3,32,32]
参数说明：
model_path ：PyTorch 模型路径（此处可任意指定，因为这种场景下只有权重文件，没有模型）
model_type ：模型类型（此处固定为 pytorch）
output ：目标模型的路径
model_def_file ：模型定义文件（必须和执行命令的路径在同一目录下）
model_class_name ：模型中定义的类别名称
model_weights_file ：模型权重文件的路径
input_shape ：模型的输入形状
5.1.3.8 PyTorch 模型转 ONNX 模型（输入仅包含权重，且模型定义在 Torchvision 中）
操作步骤
1. 执行以下命令，将 PyTorch 模型转为 ONNX 模型（输入仅包含权重，且模型定义在 Torchvision 中） 。
python -m maca_converter --model_path ./xxx --model_type pytorch --output ./
,→output.onnx --model_class_name torchvision.models.resnet50 --model_weights_
,→file ./0.9696.pth --input_shape [16,3,256,256]
参数说明：
model_path ：PyTorch 模型路径（此处可任意指定，因为这种场景下只有权重文件，没有模型）
model_type ：模型类型（此处固定为 pytorch）
output ：目标模型的路径
model_class_name ：模型中定义的类别名称
input_shape ：模型的输入形状
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 22
AI 推理用户手册
5.1.3.9 Darknet 模型转 ONNX 模型
操作步骤
1. 执行以下命令，将 Darket 模型转为 ONNX 模型。
python -m maca_converter --model_path ./my_model --model_type darknet --output ./
,→output.onnx
参数说明：
model_path ：Darknet 模型路径（文件夹，需包含.cfg 和.weights 文件）
model_type ：模型类型（此处固定为 darknet）
output ：目标模型的路径
5.1.3.10 PaddlePaddle 模型转 ONNX 模型（输入包含权重和定义）
操作步骤
1. 执行以下命令，将 PaddlePaddle 模型转为 ONNX 模型（输入包含权重和定义） 。
python -m maca_converter --model_path ./paddle_model --model_type paddle --
,→output ./output.onnx
参数说明：
model_path ： PaddlePaddle 模型路径 （文件夹， 需包含.pdmodel， .pdiparams.info 和.pdiparams
文件）
model_type ：模型类型（此处固定为 paddle）
output ：目标模型的路径
5.1.3.11 PaddlePaddle 模型转 ONNX 模型（输入仅包含权重）
操作步骤
1. 执行以下命令，将 PaddlePaddle 模型转为 ONNX 模型（输入仅包含权重） 。
python -m maca_converter --model_path ./xxx --model_type paddle --output ./
,→paddle.onnx --model_def_file ./mnist.py --model_class_name LeNet --model_
,→weights_file ./paddle_checkpoint/final.pdparams --input_shape [1,1,28,28]
参数说明：
model_path ：PaddlePaddle 模型路径（可任意指定，因为此场景下只有权重文件，没有模型）
model_type ：模型类型（此处固定为 paddle）
output ：目标模型的路径
model_def_file ：模型定义文件（必须和执行命令的路径在同一目录下）
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 23
AI 推理用户手册
model_class_name ：模型中定义的类别名称
model_weights_file ：模型权重文件的路径
input_shape ：模型的输入形状
5.1.3.12 PaddlePaddle 模型转 ONNX 模型（输入仅包含权重，模型在 paddle.vision 中定义）
操作步骤
1. 执行以下命令，将 PaddlePaddle 模型转为 ONNX 模型（输入仅包含权重，模型在 paddle.vision 中
定义） 。
python -m maca_converter --model_path ./xxx --model_type paddle --output ./
,→paddle.onnx --model_class_name paddle.vision.models.LeNet --model_weights_file 
,→./final.pdparams --input_shape [1,1,28,28]
参数说明：
model_path ：PaddlePaddle 模型路径（此处可任意指定，因为这种场景下只有权重文件，没有模
型）
model_type ：模型类型（此处固定为 paddle）
output ：目标模型的路径
model_class_name ：模型中定义的类别名称
model_weights_file ：模型权重文件的路径
input_shape ：模型的输入形状
5.1.3.13 动态 Batch 转换
操作步骤
1. 执行以下命令，将 BatchSize 非动态的模型转换为动态模型。
python -m maca_converter --model_path ./caffe_model --model_type caffe --output .
,→/output.onnx --dynamic_batch 1
5.1.3.14 ONNX 简化
操作步骤
1. 执行以下命令，对输入的模型进行常规优化（如常量折叠，Conv+BN 融合等） 。
python -m maca_converter --model_path ./test.onnx --model_type onnx --output ./
,→output.onnx
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 24
AI 推理用户手册
注解: 该功能默认打开。如需关闭，可加参数 –simplify 0。
5.1.3.15 FP32 转 FP16
操作步骤
1. 执行以下命令，将模型中相关算子的输入类型由 Float32 改为 Float16。
python -m maca_converter --model_path ./test.onnx --model_type onnx --output ./
,→output.onnx --fp32_to_fp16 1
5.1.3.16 子图提取
操作步骤
1. 执行以下命令，按照给定的 input/output，提取子图，保存模型。
python -m maca_converter --model_path ./test.onnx --model_type onnx --output ./
,→output.onnx --extract_sub 1 --inputs input_1 --outputs functional_1/
,→concatenate/concat
5.1.3.17 op_set 版本转换
操作步骤
1. 执行以下命令，转换 ONNX 模型的 op_set 版本。
python -m maca_converter --model_path ./test.onnx --model_type onnx --output ./
,→output.onnx --op_set 13
5.1.3.18 Pad 融合
操作步骤
1. 执行以下命令，将模型中相邻的 Pad+Pool 组合，融合进 Pool 算子里。
python -m maca_converter --model_path ./test.onnx --model_type onnx --output ./
,→output.onnx --fuse_pad_pool 1
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 25
AI 推理用户手册
5.1.3.19 Float32 转 Uint8（仅针对模型的 input 数据，非所有算子）
操作步骤
1. 执行以下命令，将模型的输入类型由 Float32 改为 Uint8。
python -m maca_converter --model_path ./test.onnx --model_type onnx --output ./
,→output.onnx --fp32_to_u8 1
5.1.3.20 MatMul+Add 融合为 Gemm
操作步骤
1. 执行以下命令，支持将模型中的 Matmul+Add 算子转换成 Gemm 算子（需要满足一定条件，内部会
自动判断） 。
python -m maca_converter --model_path ./test.onnx --model_type onnx --output ./
,→output.onnx --matmul_to_gemm 1
注解: 该功能默认打开。如需关闭，可加参数 –-matmul_to_gemm 0。
5.1.3.21 MHA 融合
操作步骤
1. 执行以下命令，支持将 KQV 组合融合成 MultiHeadAttentionV1 算子。
python -m maca_converter --model_path ./test.onnx --model_type onnx --output ./
,→output.onnx --fuse_mha 1
注解: 该功能默认打开。如需关闭，可加参数 –-fuse_mha 0。
5.2 MacaPrecision
GPU 开发过程中，针对 ONNX 模型中每一个算子，需要验证其在 GPU 硬件上的计算结果是否正确，以
保证相关算子软硬件实现的可靠性。MacaPrecision 是用于保证整个流程完备性的精度对比工具。
MacaPrecision 主要实现以下三个方面的功能：
• 逐层比较 AI 模型在 GPU 与 CPU 上的运行输出结果。
• 支持全量比较与指定节点比较两种方式。
• 单层计算结果的精度对比，支持 SNR/Cosine/MSE 三种方式。
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 26
AI 推理用户手册
5.2.1 安装
MacaPrecision 以 wheel 安 装 包 的 形 式 对 外 发 布， 建 议 在 Conda 环 境 中 安 装 （建 议 Python 版 本
为 3.10） 。安装 MacaRT 后，可以在/opt/maca‑ai/onnxruntime‑maca/python/tools 目录下找到
MacaPrecision 对应的 Python 安装包。
操作步骤
1. 执行以下命令，安装 MacaPrecision。
conda create -n maca_test python=3.10
source activate maca_test
pip install onnxruntime_gpu-1.12.0+mc*.whl
pip install maca_precision-*.whl
wheel 包安装过程中会自动下载相关依赖库，主要有：
• onnx
• onnxruntime‑gpu
• numpy
5.2.2 使用说明
MacaPrecision 以 CPU 计算结果为基准，对比每一层的输出结果，误差超过一定范围，认为计算精度有
误。具体流程如下：
1. 加载 ONNX 模型。
2. 解析 ONNX 模型，分析 input 变量，生成随机输入数据。
3. 在 CPU 上运行模型，保存输出结果（output_cpu） 。
4. 在 GPU 上运行模型，保存输出结果（output_gpu） 。
5. 逐层比较 output_cpu 与 output_gpu，如某一层的差值超过预设的阈值，则认为 GPU 计算精度存
在问题，需要排查。
由于常规模型与量化模型在内部处理方式上存在差异，所以执行操作时需要区分常规模型与量化模型。
5.2.2.1 常规模型（FP32/FP16）
全量模式
执行以下命令，在全量模式下进行常规模型推理。
python -m maca_precision -i ./test.onnx -c snr -t common -b 6
• 参数 -i 指定需要测试的模型路径；
• 参数 -c 指定用于逐层对比的计算方法，支持 snr/mse/cosine 三种方式（可不指定，默认 snr） ；
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 27
AI 推理用户手册
• 参数 -t 指定模型类型，此处固定为 common；
• 参数 -b 指定每次比较的中间节点的个数，可不指定，默认为 5（此处需要分批比较的原因是中间结果
的参数量可能会比较大，如果直接全部比较会占用大量显存，如指定‑1，则一次进行全量比较） 。
全量模式下，会首先进行最后一层的比较，如果结果一致，则认为模型推理无异常，不会进行中间节点
的比较。
指定模式
执行以下命令，在指定模式下进行常规模型推理。
python -m maca_precision -i ./test.onnx -c snr -t common -m Conv_0,Relu_1
参数 -m 指定需要比较的中间节点的名称，多个名称以逗号分隔。
指定模式下，无论最终的结果是否一致，都会进行指定的中间节点的比较。
5.2.2.2 量化模型（经过 MacaQuantizer 量化后的模型）
量化模型的操作与常规模型基本一致，也分为全量模式和指定模式。指定模式下的节点，只能为量化节
点。
唯一不同的是，-t 参数需要指定为 quantize。
例如：
python -m maca_precision – i ./test.onnx – t quantize -b 3
或
python -m maca_precision – i ./test.onnx – t quantize – m PPQ_Operation_152,PPQ_
,→Operation_160
5.3 MacaQuantizer
MacaQuantizer 是一个高效的神经网络量化工具，通过自定义的量化算子库、网络执行器、神经网络调
度器、量化计算图等设计，即便在网络极度复杂的情况下，依然能够得到正确的网络量化结果。量化过
程中会通过读取配置参数文件，自动搜索最优的量化方案，同时量化中严格控制硬件模拟误差，保证硬
件推理时的精度。
目前 MacaQuantizer 使用 ONNX（opset 11~13）模型文件作为输入，覆盖常用的 80 余种 ONNX 算子
类型。如果是 PyTorch，TensorFlow 等其他模型，可使用 MacaConverter 将模型转换为 ONNX 模型。
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 28
AI 推理用户手册
5.3.1 安装
操作步骤
1. 安装 Python（建议版本为 3.10） 。
安 装 MacaRT 后， 可 以 在 /opt/maca‑ai/onnxruntime‑maca/python/tools 目 录 下 找 到
MacaQuantizer 对应的 Python 安装包。
2. 执行以下命令，安装 MacaQuantizer。
pip install maca_quantizer-xxxx-py3-none-any.whl
5.3.2 使用说明
为了提高量化速度，MacaQuantizer 量化工具可以使用沐曦通用 GPU 进行量化加速。使用沐曦通用
GPU 可以加速量化过程中的重训练过程，提高量化速度。
默认采用沐曦通用 GPU 进行加速计算。如果没有沐曦通用 GPU 环境，可以使用 CPU 版本进行量化工
具，通过设置以下环境变量来进行 GPU 版和 CPU 版切换。环境变量设置为 0 时表示使用 CPU 版本进行
加速计算，为 1 时表示使用沐曦通用 GPU 进行加速计算。
export MACA_QUANTIZER_USING_MXGPU=0
运行 MacaQuantizer 之前，需要配置一个 yaml 格式的参数文件。格式如下所示：
import_model: /path/to/mode.onnx
export_model: /path/to/export_model.onnx
export_type: onnx
export_batch: 1
quant_algorithm: percentile
output_threshold: 0.1
without_bs: False
force_advance_quant: False
collecting_device: gpu
dataset:
calib_dir: /path/to/dataset/calibrate/
calib_num: 200
batch_size: 8
preprocessing:
enable: True
attributes:
isreverse: False
mean: [123.76, 116,28, 103,53]
std: [58.4, 57.12, 57.37]
resize:
keep_ratio: False
to: [3, 256, 256]
centercrop: [224, 224]
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 29
AI 推理用户手册
其中每个参数的说明，参见表 5.3。
表 5.3 参数说明
参数 值 默认值 说明
import_model 输入模型路径，目前只支持 ONNX 模型
export_model 输出模型路径，目前只支持 ONNX 模型
export_type [onnx, native] onnx 导出模型的类型
onnx：导出 onnx qdq 格式
native： 导出 qdq 格式外， 额外导出二进
制的模型
quant_algorithm [percentile, min‑
max,mse, kl]
percentile 量化算法选择
export_batch [True, False] 1 导出模型的 BatchSize，默认为 1
output_threshold 0‑1 0.1 量化后 SNR 误差最大允许范围
without_bs [True, False] False 模型输入是否带有 BatchSize 维度
force_advance_quant [True, False] False 是否量化过程中开启强制优化
calib_dir 校准数据集的目录或 dataset.txt 路径。 如
果模型为多输入，仅支持 dataset.txt 文
本格式，且数据为 npy 或二进制数据
calib_num [50‑500] 校准数据集的数量
batch_size 量化计算时的 BatchSize
enable [True, False] 是否对数据做预处理
False：校准数据需要是 npy 或二进制数
据
isreverse [True, False] 是否将图像通道 RGB 转为 BGR
mean 预处理均值
std 预处理方差。
keep_ratio [True, False] Resize 是否保持等比例。
to Resize 大小 [chw]。
pad_value 0 Resize 边缘填充的值。
centercrop [True, False] False centercrop 大小 [h, w]。
如不需要 centercrop，可删除该参数。
操作步骤
1. 执行以下命令，运行模型量化。
python -m maca_quantizer -c quantize.yaml
参数说明：
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 30
AI 推理用户手册
-c/--config ：yaml 参数文件
5.3.2.1 预处理说明
预处理流程如图 5.2 所示。
图 5.2 预处理流程
如果提供的预处理方案与模型的预处理方式不一致或无法满足要求时，可将预处理后的数据离线保存为
npy 或二进制格式，关闭数据读取时的预处理，直接读取预处理后的数据。
yaml 示例如下所示：
import_model: /path/to/mode.onnx
export_model: /path/to/export_model.onnx
export_type: onnx
quant_algorithm: percentile
export_batch: 1
without_bs: False
force_advance_quant: False
dataset:
calib_dir: /path/to/dataset/calibrate/
calib_num: 200
batch_size: 8
preprocessing:
enable: False
5.3.2.2 dataset.txt文本格式说明
若输入 calib_dir 为 dataset.txt 文本格式，请参考如下格式。
• 单输入模型：只读取每行第一列参数（空格分割） ；
val/ILSVRC2012_val_00000001.JPEG 66
val/ILSVRC2012_val_00000002.JPEG 971
val/ILSVRC2012_val_00000003.JPEG 231
val/ILSVRC2012_val_00000004.JPEG 810
val/ILSVRC2012_val_00000005.JPEG 517
val/ILSVRC2012_val_00000006.JPEG 58
val/ILSVRC2012_val_00000007.JPEG 335
val/ILSVRC2012_val_00000008.JPEG 416
val/ILSVRC2012_val_00000009.JPEG 675
• 多输入模型：每一行为一个数据样本，输入空格分割。
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 31
AI 推理用户手册
1000000000_input_ids.npy 1000000000_input_mask.npy 1000000000_segment_ids.npy
1000000001_input_ids.npy 1000000001_input_mask.npy 1000000001_segment_ids.npy
1000000002_input_ids.npy 1000000002_input_mask.npy 1000000002_segment_ids.npy
1000000003_input_ids.npy 1000000003_input_mask.npy 1000000003_segment_ids.npy
1000000004_input_ids.npy 1000000004_input_mask.npy 1000000004_segment_ids.npy
1000000005_input_ids.npy 1000000005_input_mask.npy 1000000005_segment_ids.npy
5.3.3 注意事项
• 目前只支持 ONNX 模型的量化，如果不是，建议量化前使用 MacaConverter 对模型进行转换。
• 目前只支持 ONNX（opset 11~13）模型文件作为输入，如果不是，建议量化前使用 MacaConverter
对模型转换。
• 目前 MacaQuantizer 支持的算子参见表 5.4：
表 5.4 MacaQuantizer 支持的 ONNX 算子
Gemm ReduceMean Sqrt
grid_sampler ReduceSum Log
GlobalAveragePool Relu Floor
GlobalMaxPool Reshape RoiAlign
Greater Resize MMCVRoiAlign
LeakyRelu ScatterElements SpaceToDepth
Less ScatterND DepthToSpace
MatMul Shape Tanh
Max Sigmoid Pow
MaxPool Slice InstanceNormalization
Min Softmax HardSigmoid
Mul Softplus HardSwish
NonMaxSuppression Split Neg
NonZero Squeeze GRU
Not Sub Swish
Pad Tile Identity
PRelu TopK OneHot
Range Transpose Reciprocal
ReduceL2 Unsqueeze Mish
ReduceMax Where Elu
Sum Erf
5 MacaRT 工具链 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 32
AI 推理用户手册
6 MacaRT‑LLM
6.1 MacaRT‑LLM 介绍
MacaRT‑LLM 是在沐曦通用 GPU 上进行大模型部署和执行的推理引擎，是在 MXMACA 后端适配了
OpenPPL‑LLM。 使用 MacaRT‑LLM 在沐曦通用 GPU 上进行大模型推理， 其方法和功能与 OpenPPL‑LLM
完全兼容。
OpenPPL‑LLM 进行大模型推理的整体流程，如图 6.1 所示，可以分为以下部分：
1. LLM 模型转换，使用 MacaPMX 将 LLM 原始模型转换成 OpenPPL‑LLM 支持的 ONNX 模型。
2. 在 PPL.NN.LLM 上对模型图进行处理，包括图优化、图拆分、图编译等。
3. 适配 PPL.LLM Serving，支持 LLM 云端服务。
4. PPL.LLM Kernel Library 通过 MXMACA Driver 在沐曦通用 GPU 上执行模型。
图 6.1 OpenPPL‑LLM 大模型推理流程图
6.2 MacaRT‑LLM 功能
MacaRT‑LLM 完全适配了 OpenPPL‑LLM，包含了以下功能和特性：
• 完全适配 PPL.PMX，提供 MacaPMX 支持多种主流大模型进行模型转换。
• 完全适配 PPL.NN.LLM，支持多个主流大模型的推理和模型切分多卡并行推理。
• 完全适配 PPL.LLM.Serving，支持大模型服务化部署。
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 33
AI 推理用户手册
6.3 MacaRT‑LLM 使用流程
本章节介绍 MacaRT‑LLM 的使用步骤，主要分为模型转换、本地模型部署验证及服务化部署三个部分。
6.3.1 模型转换
使用 MacaPMX 进行模型转换，MacaPMX 与 PPL.PMX 完全适配，为每个 OP 提供了一组标准的操作符
规范文档和相应的函数 Python API，使用户可以轻松地在 Python 中使用 PMX 自定义的 OP 构建需要的
模型。
目前， MacaPMX 主要负责 LLM 模型结构的表达。 除了 PPL.PMX 提供的开箱即用的 LLM model zoo， 用
户还可使用 MacaPMX 提供的模型转换工具（从不同社区的模型到 PMX 模型） 、Tensor 并行分割工具和
PMX 模型合并工具。
6.3.1.1 安装
MacaPMX 以 wheel 安装包的形式对外发布，建议在 Conda 环境中安装（建议 Python 版本 3.8） 。
操作步骤
1. 下载解压相应发行版的 ppl.llm.serving 发布包 （例如：maca‑ppl.llm.serving‑py38‑2.33.0.11‑
linux‑x86_64.tar .xz）后，在解压路径/wheel 下找到 macapmx 对应的 Python 安装包。
2. 执行以下命令，安装 MacaPMX。
conda create -n maca_test python=3.8
source activate maca_test
pip install macapmx-*-py3-none-any.whl
wheel 包的依赖库主要有：
• onnx
• torch
• fire
• sentencepiece
• safetensors
其中，torch 应为安装相应的沐曦通用 GPU 软件发布包后得到的版本，其余依赖库会在安装 MacaPMX
时自动安装。
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 34
AI 推理用户手册
6.3.1.2 转换为 PMX 模型
操作步骤（以 llama‑7b 为例）
1. 解压 ppl.llm.serving 发布包后，在解压路径 /ai_deb 中可以看到适配后的 ppl.llm.serving 安装
包（ppl.llm.serving_*.deb） ，执行以下命令进行安装。
sudo dpkg -i ppl.llm.serving_*.deb
2. 安装完成后，在 /opt/maca‑ai/ppl.llm.serving/samples/samples/model_converter/路径下
获取 PMX 模型转换示例脚本 ConvertWeightToPmx.py。
根据需要，修改第 4 行导入相应模型的转换函数。当前支持的模型及对应导入代码参见表 6.1。
表 6.1 MacaPMX 支持的大模型及对应转换函数
LLM Model ConvertWeightToPmx.py导入代码
Llama 全系/其它类 Llama 大模
型
from macaPMX.model_zoo.llama.huggingface import
write_pmx_model
chatglm2_6B/chatglm3_6B from macaPMX.model_zoo.chatglm2.huggingface import
write_pmx_model
internlm_7B from macaPMX.model_zoo.internlm.huggingface import
write_pmx_model
BaiChuan2_7B from macaPMX.model_zoo.baichuan.huggingface import
write_pmx_model
Mixtral8x7B from macaPMX.model_zoo.mixtral.huggingface import
write_pmx_model
QWen 系列模型 from macaPMX.model_zoo.qwen.huggingface import
write_pmx_model
注解: Llama 系列对应的 PMX 转换函数， 支持的参数与其它模型不同， 支持转换safetensors
格式的原始权重，若使用 use_safetensors 参数，需要取消示例代码中 16‑21 行及 26 行的注
释。该参数仅在 Llama 系列模型上生效，其余模型不能设置该参数，否则程序会执行失败。
3. 执行以下命令，将 LLM 原始权重转换为 PMX 模型。
python ConvertWeightToPmx.py --input_dir <hf_model_dir> --output_dir <pmx_model_
,→dir> --use_safetensors True
参数说明：
• input_dir ：LLM 原始权重模型路径（文件夹）
• output_dir ：输出 PMX 模型目标路径（文件夹）
• use_safetensors ：原始权重文件格式是否为 safetensors，仅 Llama 系列支持该参数
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 35
AI 推理用户手册
6.3.1.3 模型切分
当模型需要在多卡环境上进行并行推理时，需要将生成的 PMX 模型进行切分，以适应多卡并行推理。
操作步骤
1. 在/opt/maca‑ai/ppl.llm.serving/samples/samples/model_converter/路径下获取 PMX 模型
切分示例脚本 Split.py。
根据需要，修改第 2 行导入相应模型的切分函数。当前支持的模型及对应导入代码参见表 6.2。
表 6.2 MacaPMX 支持的大模型及对应 PMX 切分函数
LLM Model Split.py 导入代码
Llama/Qwen/其 它 类 Llama 大
模型
import macaPMX.model_zoo.llama.modeling.SplitModel
as SplitModel
Mixtral8x7B import macaPMX.model_zoo.mixtral.modeling.SplitModel
as SplitModel
2. 执行以下命令，进行模型拆分。
python Split.py --input_dir <input_directory_path> --num_shards <number_of_
,→shards> --output_dir <output_directory_path>
参数说明：
• input_dir ：待切分 PMX 模型路径（文件夹）
• num_shards ：PMX 模型切分份数
• output_dir ：切分后 PMX 模型目标路径（文件夹）
6.3.1.4 模型合并（可选）
该操作与模型切分相反，将多个切分后的 PMX 模型合并成一个。
操作步骤
1. 在/opt/maca‑ai/ppl.llm.serving/samples/samples/model_converter/路径下获取 PMX 模型
合并示例脚本 Merge.py。
根据需要，修改第 2 行导入相应模型的合并函数。当前支持的模型及对应导入代码参见表 6.3。
表 6.3 MacaPMX 支持的大模型及对应 PMX 合并函数
LLM Model Merge.py 导入代码
Llama/Qwen/其 它 类 Llama 大
模型
import macaPMX.model_zoo.llama.modeling.MergeModel
as MergeModel
下页继续
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 36
AI 推理用户手册
表 6.3 – 续上页
LLM Model Merge.py 导入代码
Mixtral8x7B import macaPMX.model_zoo.mixtral.modeling.MergeModel
as MergeModel
2. 执行以下命令，对切分后 PMX 模型进行合并。
python merge.py --input_dir <input_directory_path> --num_shards <number_of_
,→shards> --output_dir <output_directory_path>
参数说明：
• input_dir ：待合并 PMX 模型路径（文件夹）
• num_shards ：PMX 子模型的份数
• output_dir ：合并后 PMX 模型目标路径（文件夹）
6.3.1.5 PMX 模型测试
当生成 PMX 模型后，使用 torch 加载 PMX 模型并执行 LLM 推理，根据输出结果验证 PMX 模型转换的
正确性。同时，若设置相应 dump 参数，可以将模型对应 step 的输入、输出保存下来，作为后续本地部
署精度验证的输入及输出参考值。
操作步骤
1. 在/opt/maca‑ai/ppl.llm.serving/samples/samples/model_converter/路径下获取 PMX 模型
测试示例脚本 Demo.py。
根据需要，修改第 2 行导入相应模型的 PMX 运行函数。当前支持的模型及对应导入代码参见表 6.4。
表 6.4 MacaPMX 支持的大模型及对应 PMX 模型运行函数
LLM Model Demo.py 导入代码
Llama 全系/其它类 Llama 大模
型
from macaPMX.model_zoo.llama.huggingface import run_
demo
chatglm2_6B/chatglm3_6B from macaPMX.model_zoo.chatglm2.huggingface import
run_demo
internlm_7B from macaPMX.model_zoo.internlm.huggingface import
run_demo
BaiChuan2_7B from macaPMX.model_zoo.baichuan.huggingface import
run_7B
Mixtral8x7B from macaPMX.model_zoo.mixtral.huggingface import
run_demo
QWen 系列模型 from macaPMX.model_zoo.qwen.huggingface import run_
demo
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 37
AI 推理用户手册
注解: BaiChuan2_7B 对应的 PMX 运行函数与其余模型不同，需要同步修改第 5 行中的函数名。
2. 执行以下命令，验证 PMX 模型精度。
OMP_NUM_THREADS=1 torchrun --nproc_per_node $num_gpu Demo.py --ckpt_dir <llama_
,→dir> --tokenizer_path <llama_tokenizer_dir>/tokenizer.model --fused_qkv 1 --
,→fused_kvcache 1 --auto_causal 1 --quantized_cache 1 --dynamic_batching 1 --
,→seqlen_scale_up 1 --max_gen_len 256 --dump_steps 0,1,255 --dump_tensor_path
,→<dump_dir> --batch 1 --cache_layout 3
参数说明：
num_gpu ：模型推理需要的 GPU 数量
ckpt_dir ：PMX 模型路径
tokenizer_path ：tokenizer 模型路径
当需要保存测试数据时，设置以下参数：
seqlen_scale_up：输入字节大小的比例因子（序列长度按 8 放大）
max_gen_len ：指定生成的最大输出长度（以字节为单位）
dump_steps ：保存测试数据的 step，可以指定多个 step，以“,”分隔。若只保存单个 step，必须
用“,”结尾，否则会执行失败。
dump_tensor_path ：保存测试数据的路径
batch ：指定数据处理的批大小
cache_layout ：cacheAttention 中 cache 存储 layout，当前仅支持 0 和 3。0：layout 为 [MaxT ,
L, 2, H, Dh]；3：layout 为 [L, 2, H, MaxT , Dh]。建议设置为 3，性能更佳。
其余参数与命令中保持一致即可。
注解: cache_layout 的设置需要与 6.3.1.6 导出为 ONNX 模型 中的设置一致，否则 6.3.2 本地
模型部署精度验证 会失败。
6.3.1.6 导出为 ONNX 模型
在验证 PMX 模型精度无误后，可以执行最终步骤：将 PMX 导出至 ONNX 模型。
操作步骤
1. 在/opt/maca‑ai/ppl.llm.serving/samples/samples/model_converter/路径下获取 ONNX 模
型导出示例脚本 Export.py。
根据需要， 修改第 2 行导入相应模型的 ONNX 导出函数。 当前支持的模型及对应导入代码参见表 6.5。
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 38
AI 推理用户手册
表 6.5 MacaPMX 支持的大模型及对应 ONNX 导出函数
LLM Model Export.py 导入代码
Llama 全系/其它类 Llama 大模
型
from macaPMX.model_zoo.llama.huggingface import run_
export
chatglm2_6B/chatglm3_6B from macaPMX.model_zoo.chatglm2.huggingface import
run_export
internlm_7B from macaPMX.model_zoo.internlm.huggingface import
run_export
BaiChuan2_7B from macaPMX.model_zoo.baichuan.huggingface import
export_7B
Mixtral8x7B from macaPMX.model_zoo.mixtral.huggingface import
run_export
QWen 系列模型 from macaPMX.model_zoo.qwen.huggingface import run_
export
注解: BaiChuan2_7B 对应的 ONNX 导出函数与其余模型不同，需要同步修改第 5 行中的函数
名。
2. 执行以下命令，将 PMX 模型导出为 ONNX 模型。
OMP_NUM_THREADS=1 torchrun --nproc_per_node $num_gpu Export.py --ckpt_dir <llama_
,→dir> --tokenizer_path <llama_tokenizer_dir>/tokenizer.model --fused_qkv 1 --
,→fused_kvcache 1 --auto_causal 1 --quantized_cache 1 --dynamic_batching 1 --
,→export_path <export_dir> --cache_layout 3
参数说明：
num_gpu ：模型推理需要的 GPU 数量
ckpt_dir ：PMX 模型路径
tokenizer_path ：tokenizer 模型路径；chatglm 系列模型不支持此参数，无需设置。
export_path ：导出 ONNX 模型目标路径
cache_layout ：cacheAttention 中 cache 存储 layout，当前仅支持 0 和 3。0：layout 为 [MaxT ,
L, 2, H, Dh]；3：layout 为 [L, 2, H, MaxT , Dh]。建议设置为 3，性能更佳。
其余参数与命令中保持一致即可。
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 39
AI 推理用户手册
6.3.2 本地模型部署精度验证
大多数情况下，大模型会依托服务端部署提供服务端接口供客户端调用，但在服务化部署前，需要依托
本地模型部署进行推理验证，以确认模型精度是否符合预期。本章节介绍模型本地部署及精度验证的方
法。
本地部署精度验证依赖工具如下：
pplnn_llm： 本 地 部 署 可 执 行 文 件， 安 装 ppl.llm.serving_*_amd64.deb 后 在/opt/maca‑
ai/ppl.llm.serving/bin/下获取。
操作步骤
1. 创建一个测试 bash 脚本 benchmark.sh，内容如下：
if [ -n "$MPI_LOCALRANKID" ]; then
MPI_LOCALRANKID=$MPI_LOCALRANKID
elif [ -n "$OMPI_COMM_WORLD_RANK" ]; then
MPI_LOCALRANKID=$OMPI_COMM_WORLD_RANK
elif [ -n "$PMI_RANK" ]; then
MPI_LOCALRANKID=$PMI_RANK
else
echo "[WARNING] MPI_LOCALRANKID not found, set to 0"
MPI_LOCALRANKID=0
fi
DEVICE_ID=$MPI_LOCALRANKID
STEP=$1
if [ ! -n "$STEP" ]; then
STEP=0
fi
MODEL_PATH="/path/to/exported/model/model_slice_${MPI_LOCALRANKID}/model.onnx"
OUTPUT_DIR="/path/to/output_dir/rank_${MPI_LOCALRANKID}" # we should make the  
,→rank_* directories first
TEST_DATA_DIR="/path/to/dumped/tensor/data/rank_${MPI_LOCALRANKID}"
# we should rearrange the input tensors if the model exporting parameters has  
,→been changed.
TOKEN_IDS=`ls ${TEST_DATA_DIR}/step${STEP}_token_ids-*`
ATTN_MASK=`ls ${TEST_DATA_DIR}/step${STEP}_attn_mask-*`
SEQSTARTS=`ls ${TEST_DATA_DIR}/step${STEP}_seqstarts-*`
KVSTARTS=`ls ${TEST_DATA_DIR}/step${STEP}_kvstarts-*`
CACHESTARTS=`ls ${TEST_DATA_DIR}/step${STEP}_cachestarts-*`
DECODING_BATCHES=`ls ${TEST_DATA_DIR}/step${STEP}_decoding_batches-*`
START_POS=`ls ${TEST_DATA_DIR}/step${STEP}_start_pos-*`
AX_SEQLEN=`ls ${TEST_DATA_DIR}/step${STEP}_max_seqlen-*`
MAX_KVLEN=`ls ${TEST_DATA_DIR}/step${STEP}_max_kvlen-*`
KV_CAHCE=`ls ${TEST_DATA_DIR}/step${STEP}_kv_cache-*`
KV_SCALE=`ls ${TEST_DATA_DIR}/step${STEP}_kv_scale-*`
(下页继续)
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 40
AI 推理用户手册
(续上页)
TEST_INPUTS="$TOKEN_IDS,$ATTN_MASK,$SEQSTARTS,$KVSTARTS,$CACHESTARTS,$DECODING_
,→BATCHES,$START_POS,$MAX_SEQLEN,$MAX_KVLEN,$KV_CAHCE,$KV_SCALE"
INPUT_DEVICES="device,device,device,device,device,host,device,host,host,device,
,→device"
CMD="/opt/maca-ai/ppl.llm.serving/bin/pplnn_llm --use-llm-cuda \
--onnx-model $MODEL_PATH \
--shaped-input-files $TEST_INPUTS \
--save-outputs \
--device-id $DEVICE_ID \
--save-data-dir $OUTPUT_DIR \
--in-devices $INPUT_DEVICES \
--enable-profiling \
--min-profiling-seconds 3 \
--warmup-iterations 10"
echo "RUN RANK${MPI_LOCALRANKID} STEP${STEP} -> $CMD"
eval "$CMD"
参数说明：
MODEL_PATH ：6.3.1.6 导出为 ONNX 模型中导出的 ONNX 模型路径
OUTPUT_DIR ：模型输出文件保存路径
TEST_DATA_DIR ：模型输入文件保存路径，模型输入数据的操作步骤参见 6.3.1.5 PMX 模型测试
注解: 需要将 CMD 中对应 pplnn_llm 设置为安装后放置的路径或者自定义路径，这里默认设
置为安装路径。
2. 设置环境变量并运行测试脚本生成输出数据。
export MACA_PATH=your_maca_path
export PATH=${MACA_PATH}/bin:${PATH}
export LD_LIBRARY_PATH=${MACA_PATH}/lib:${MACA_PATH}/mxgpu_llvm/lib:${MACA_PATH}/
,→ompi/lib:${LD_LIBRARY_PATH}
export USE_GEMM_NN=true
benchmark.sh <STEP> # 单 卡 推 理 测 试 命 令
mpirun -np 4 benchmark.sh <STEP> #四 卡 推 理 测 试 命 令 ，-np 参 数 设 置 与 推 理 卡 数 一 致
执 行 完 上 述 命 令 后， 会 在 设 置 的 OUTPUT_DIR 保 存 对 应 step 的 输 出 数 据。 后 续 可 以 根 据 需
求 与 6.3.1.5 PMX 模 型 测 试中 保 存 的 输 出 参 考 数 据 进 行 比 对。 输 出 数 据 格 式 为 float32， 使 用
np.fromfile(data_path, np.float32) 即可加载。
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 41
AI 推理用户手册
注解:
• 执行测试脚本前，需要激活测试环境变量，否则会测试失败。
• <STEP> 需要与 6.3.1.5 PMX 模型测试中保存的 step 相对应，否则会导致输入数据加载失败。
6.3.3 本地模型部署性能测试
为了探测特定大模型的极限性能，可以在本地进行性能测试，为后续服务端部署性能做一个参照，进而
优化服务端部署参数设置，最大限度发挥出沐曦通用 GPU 的硬件性能。
本地部署性能测试依赖工具如下：
benchmark_llama：性能测试可执行文件，安装 ppl.llm.serving_*_amd64.deb 后在/opt/maca‑
ai/ppl.llm.serving/bin/下获取。当前仅支持 llama 系列及类 llama 模型的测试。
操作步骤（以 llama‑7b 为例）
1. 创建一个测试 bash 脚本 benchmark_7b.sh，内容如下：
#!/bin/bash
MODEL_TYPE="llama"
MODEL_DIR="/mnt/hpc/shengyunrui/model_card/llama_7b_ppl"
MODEL_PARAM_PATH="/mnt/hpc/shengyunrui/model_card/llama_7b_ppl/params.json"
TENSOR_PARALLEL_SIZE=1
TOP_P=0.0
TOP_K=1
TEMPERATURE=1.0
WARMUP_LOOPS=2
BENCHMARK_LOOPS=2
INPUT_FILE_BASE="tokens_input"
INPUT_LEN=8
GENERATION_LEN=256
BATCH_SIZE_LIST=(1 2 4 8 16 32 64 128 256)
for BATCH_SIZE in ${BATCH_SIZE_LIST[@]}; do
INPUT_FILE=${INPUT_FILE_BASE}_${INPUT_LEN}
your_path_of_benchmark_llama \
--model-type $MODEL_TYPE \
--model-dir $MODEL_DIR \
--model-param-path $MODEL_PARAM_PATH \
--tensor-parallel-size $TENSOR_PARALLEL_SIZE \
--top-p $TOP_P \
--top-k $TOP_K \
(下页继续)
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 42
AI 推理用户手册
(续上页)
--temperature $TEMPERATURE \
--warmup-loops $WARMUP_LOOPS \
--generation-len $GENERATION_LEN \
--benchmark-loops $BENCHMARK_LOOPS \
--input-file $INPUT_FILE \
--batch-size $BATCH_SIZE
done
参数说明：
MODEL_TYPE ：LLM 模型类型，当前仅支持 Llama
MODEL_DIR ：6.3.1.6 导出为 ONNX 模型中导出的 ONNX 模型路径
MODEL_PARAM_PATH ：6.3.1.6 导出为 ONNX 模型中导出 ONNX 模型的 params.json 文件路径
TENSOR_PARALLEL_SIZE ：Tensor 并行大小，需要与 6.3.1.3 模型切分中模型切分数量保持一致，
即导出模型为 2 卡并行，此处设置为 2；4 卡并行则设置为 4
WARMUP_LOOPS ：warmup 执行次数，在正式测试前执行该次数的 warmup
BENCHMARK_LOOPS ：性能测试执行次数
INPUT_FILE_BASE ：模型输入文件基础文件名，默认为 tokens_input，测试输入的文件名称为
${INPUT_FILE_BASE}_${INPUT_LEN}，即通过基础文件名和输入长度拼接。例如，输入长度为
8 的输入文件名称为 tokens_input_8
INPUT_LEN ：模型输入 token 长度
GENERATION_LEN ：模型生成 token 长度
BATCH_SIZE_LIST ：性能测试 batchsize 列表，测试会遍历该列表中所有设置
输入文件为文本文件，每一行代表一条输入 token，各 token 之间用空格分隔，以 INPUT_LEN=8
为例，该文件的构成如下。篇幅限制，这里只展示前 8 条输入 token。该文件的行数（lines_of_
token） 必须大于等于测试设置的最大 batchsize， 否则该 batchsize 设置无效， 测试程序只能执行最
大 batchsize = lines_of_token 的测试，详细可参考相关文件。
1, 306, 4658, 278, 6593, 310, 2834, 338
1, 306, 4658, 278, 6593, 310, 2834, 338
1, 306, 4658, 278, 6593, 310, 2834, 338
1, 306, 4658, 278, 6593, 310, 2834, 338
1, 306, 4658, 278, 6593, 310, 2834, 338
1, 306, 4658, 278, 6593, 310, 2834, 338
1, 306, 4658, 278, 6593, 310, 2834, 338
1, 306, 4658, 278, 6593, 310, 2834, 338
2. 设置环境变量并运行测试脚本生成输出数据。
export MACA_PATH=your_maca_path
export PATH=${MACA_PATH}/bin:${PATH}
(下页继续)
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 43
AI 推理用户手册
(续上页)
export LD_LIBRARY_PATH=${MACA_PATH}/lib:${MACA_PATH}/mxgpu_llvm/lib:${LD_LIBRARY_
,→PATH}
export USE_GEMM_NN=true
benchmark_7b.sh
执行完上述命令后，会输出对应设置下的性能测试数据，如下所示：
CSV format header:prefill(ms),decode(ms),avg(ms),tps(ms),mem(gib)
CSV format output:40.16,14.2576,14.4599,69.1567,14.3461
分别对应 prefill 耗时、平均 decode 延迟、平均 step 延迟、tokens 吞吐 （tokens per second） 以及
显存使用。
注解: 执行测试脚本前，需要激活测试环境变量，否则会测试失败。
6.3.4 服务化部署
大模型服务化部署是一种将大模型应用于实际场景的有效方式。它具有以下优势：
• 提供更高的性能和更准确的结果。由于大模型具备更深层次的理解和更复杂的参数配置，其在各种任
务上表现更出色。通过将大模型部署为服务，可以利用其强大的计算能力和学习能力，为用户提供更
高质量的预测、推荐和决策。
• 可以实现灵活的扩展性和定制化需求。采用服务化架构，可以将模型与其他组件解耦，使得系统更易
于扩展和维护。同时，根据不同业务需求，可以对大模型进行个性化的调整和优化，以满足特定任务
的要求。
• 提升数据安全和隐私保护。通过将模型部署在云端或私有环境中，可以有效保护敏感数据的安全性，
避免将数据传输到公共网络或设备中。这种集中化的方式可以通过严格的权限控制和加密技术来保护
用户数据的隐私。
总的来说，大模型服务化部署具有性能优越、灵活扩展和安全保护等诸多优势，可为各行各业提供更高
水平的智能服务。
本节将从服务端部署、C++ 客户端部署、Python 客户端部署三个部分介绍服务化部署。
6.3.4.1 服务端部署
服务端部署依赖文件如下：
• ppl_llm_server： 服务端部署可执行文件， 安装ppl.llm.serving_*_amd64.deb 后在/opt/maca‑
ai/ppl.llm.serving/bin/下获取。
• xxx_config.json： 特 定 大 模 型 配 置 文 件， ppl_llm_server 通 过 解 析 该 配 置 文 件
加 载 并 运 行 对 应 的 模 型。 安 装 ppl.llm.serving_*_amd64.deb 后， 在 /opt/maca‑
ai/ppl.llm.serving/samples/samples/ppl_server_client/model_config/ 路 径 下， 可 找 到 当
前所有已支持模型的配置示例。
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 44
AI 推理用户手册
操作步骤（以 llama‑7b 为例）
1. 创建 llama_7b_config.json，主要内容如下：
{
"model_type": "llama",
"model_dir": "/path/to/model/dir",
"model_param_path": "/path/to/model/dir/params.json",
"tokenizer_path": "/path/to/tokenizer/tokenizer.model",
"tensor_parallel_size": 1,
"top_p": 0.0,
"top_k": 1,
"quant_method": "none",
"max_tokens_scale": 0.6,
"max_tokens_per_request": 4096,
"max_running_batch": 1024,
"max_tokens_per_step": 8192,
"host": "0.0.0.0",
"port": 23333
}
参数说明：
model_type ： LLM 模型类型， 可参考/opt/maca‑ai/ppl.llm.serving/samples/samples/ppl_
server_client/model_config 中已支持模型的配置示例进行配置
model_dir ：6.3.1.6 导出为 ONNX 模型中导出的 ONNX 模型路径
model_param_path ：6.3.1.6 导出为 ONNX 模型中导出 ONNX 模型的 params.json 文件路径
tokenizer_path ：tokenizer 模型路径
tensor_parallel_size ：Tensor 并行大小，需要与 6.3.1.3 模型切分中模型切分数量保持一致，
即导出模型为 2 卡并行，此处设置为 2；4 卡并行则设置为 4
max_tokens_scale ：设置范围 [0.1, 0.9]，该参数会影响服务端对显存的使用。简单地说，代表模
型加载完成后，额外占用剩余显存的比例，受制于当前显存碎片化管理不够完善，随着请求次数增
加，显存会出现溢出，建议设置一个较小的值。若测试大 batchsize，建议设置大一些（0.9） ，否则
由于预分配显存不够，无法按照设定的 batchsize 执行大模型推理，但此时请求的次数要比较少，否
则也会出现显存溢出
max_tokens_per_request ：单次请求的最大 token 数，建议设置 4096
max_running_batch ：执行推理最大 batchsize
max_tokens_per_step ：单个 step 处理最大 token 数
2. 设置环境变量并运行服务端程序，启动 llama_7b 服务。
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 45
AI 推理用户手册
export MACA_PATH=your_maca_path
export PATH=${MACA_PATH}/bin:${PATH}
export LD_LIBRARY_PATH=${MACA_PATH}/lib:${MACA_PATH}/mxgpu_llvm/lib:${LD_LIBRARY_
,→PATH}
export USE_GEMM_NN=true
export SHOW_PREFILL=true # 若 需 要 输 出prefill 性 能 统 计 数 据 ， 设 置 该 环 境 变 量
./ppl_llm_server llama_7b_config.json
当输出下列日志时，表示 llama_7b 服务启动完成：
[INFO][2023-12-07 16:05:29.304][llama_worker.cc:962] waiting for request ...
6.3.4.2 C++ 客户端部署
安装 ppl.llm.serving_*_amd64.deb 后， 可在/opt/maca‑ai/ppl.llm.serving/samples/samples/ppl_
server_client/cpp_client/路径下获取 C++ 代码示例。安装路径中有该代码示例已编译生成的可执行
文件：/opt/maca‑ai/ppl.llm.serving/bin/cpp_client。工程文件目录如图 6.2 所示：
• cmake：文件夹，包含三方依赖库 cmake 配置。
• CMakeLists.txt：CMake 配置文件。
• proto：文件夹，包含与服务端交互时 grpc 依赖的 proto 文件。
• src：文件夹，包含 client_sample.cc，是 C++ 客户端的简单使用示例程序。
图 6.2 C++ 客户端目录结构图
参考 client_sample.cc 示例代码，根据业务需求定制相应的 C++ 客户端即可。
编译时需要将 cmake/deps.cmake 中 37‑39 行、41‑43 行中 grpc、absl 依赖库地址修改为：
hpcc_declare_git_dep(grpc
https://github.com/grpc/grpc.git
v1.56.2)
hpcc_declare_git_dep(absl
https://github.com/abseil/abseil-cpp.git
lts_2023_01_25)
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 46
AI 推理用户手册
6.3.4.3 Python 客户端部署
安装 ppl.llm.serving_*_amd64.deb 后， 可在/opt/maca‑ai/ppl.llm.serving/samples/samples/ppl_
server_client/python_client/路径下获取 Python 代码示例。工程文件目录如图 6.3 所示：
• llm_pb2.py：与服务端交互时 grpc 依赖的 proto 定义文件。
• llm_pb2_grpc.py：与服务端交互时 grpc 依赖的 proto 定义文件。
• client.py：Python 客户端示例脚本。
图 6.3 Python 客户端目录结构图
参考 client.py 示例代码，根据业务需求定制相应的 Python 客户端即可。
Python 客户端依赖 grpc，使用时需安装 grpcio、grpcio‑tools 两个依赖项。
pip install grpcio
pip install grpcio-tools
6.3.4.4 服务端输出性能数据解析
服务端完成部署，客户端成功发送请求，服务端完成请求的处理并将结果发送至客户端后，服务端会输
出当前部署大模型的性能数据。示例如图 6.4 所示：
图 6.4 服务端输出性能数据示例（llama‑7b）
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 47
AI 推理用户手册
若在启动服务前设置 SHOW_PREFILL 环境变量，服务端会输出 prefill 阶段的性能数据，即 图 6.4 中
step1 的性能数据；若不设置，则输出 100 整数倍及最后一个 step 的性能数据。
重点性能参数包括：
memory usage ：当前 step 显存使用情况
running batch ：当前 step 正在推理的 batchsize
max running batch ：从当前 step 回溯的历史最大推理 batchsize
finished query count ：当前 step 已经结束生成的请求数量
pipeline ：整体流程耗时，包含当前 step 耗时，平均耗时及总耗时
model inference ：大模型推理的耗时，包含当前 step 耗时，平均耗时及总耗时
6 MacaRT‑LLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 48
AI 推理用户手册
7 MacaRT‑vLLM
7.1 MacaRT‑vLLM 介绍
MacaRT‑vLLM 是在沐曦通用 GPU 上适配官方 vLLM 的推理工具，基于 MXMACA 后端对 vLLM 方法进行
了兼容适配和 Kernel 优化。使用 MacaRT‑vLLM 在沐曦通用 GPU 上进行大模型推理，其方法和功能与
官方 vLLM 兼容。当前兼容版本为 vLLM‑0.8.2。
vLLM 版本与 PyTorch 版本的兼容适配关系，参见表 7.1。
表 7.1 vLLM 与 PyTorch 的版本兼容关系
vLLM PyTorch
0.6.2 2.1
0.6.6 2.1
0.7.2 2.4
0.8.2 2.4
7.2 MacaRT‑vLLM 功能与局限性
MacaRT‑vLLM 兼容适配了 vLLM‑0.8.2，包含了以下功能和特性，以及局限性：
功能和特性：
• 兼容 vLLM‑0.8.2 支持的所有模型 BFLOAT16 推理和部分模型 FLOAT16 推理，支持官方多模态模型
• 兼容原生 LLM、Engine、Kernel 的 API 接口
• 兼容原生 server 和 OpenAI server 接口
• 支持 Lora 特性
• 支持 GPTQ 和 AWQ 量化方式
• 支持 ray 和 mp 方式启动单机多卡推理；设置 --distributed-executor-backend 可以指定不同
后端进行多卡推理，默认使用 ray
• 支持 prefix_cache 方式
• 支持 enforce_eager=False 方式。需通过显式配置，默认为True。另外，需要额外设置 MACA 环
境变量来获取加速效果：export MACA_GRAPH_LAUNCH_MODE=1
局限性：
• 不支持 FP8 类型 KV Cache 和相关 FP8 模型
• 包含 Ubuntu 20、Ubuntu 22、kylin2309a 系统版本，后续完善支持其他系统
7 MacaRT‑vLLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 49
AI 推理用户手册
7.3 MacaRT‑vLLM 使用流程
本章节介绍 MacaRT‑vLLM 的使用步骤，主要分为离线推理、吞吐测试和 Sever 服务。
7.3.1 环境准备
使用 MacaRT‑vLLM 进行推理需要准备好环境。目前提供两种方式：镜像和 wheel 包。
7.3.1.1 使用 vLLM 镜像
从沐曦开发者中心的镜像资源中心获取镜像。
选择合适的架构类型、操作系统类型、Python 版本后，点击 docker 命令复制，获取此 Docker 镜像的
拉取命令。
创建容器环境示例如下：
export IMAGE=cr.metax-tech.com/public-ai-release/maca/vllm:maca.ai3.1.0.7-torch2.6-
,→py310-ubuntu22.04-amd64
sudo docker run -it --privileged --cap-add=SYS_PTRACE --security-opt 
,→seccomp=unconfined \
--device=/dev/dri --device=/dev/mxcd --device=infiniband --group-add video --
,→name vllm_metax --network=host \
--security-opt apparmor=unconfined --shm-size '100gb' --ulimit memlock=-1 \
-v /mnt:/mnt \
$IMAGE \
/bin/bash
sudo docker exec -it vllm_metax /bin/bash
7.3.1.2 安装 wheel 包
操作步骤
1. 预先安装沐曦平台的 torch、flash attn、xformer（可选）环境。
2. 获取 MacaRT‑vLLM 压缩包 maca‑vllm‑py310‑xxx‑${OS_Version}.tar .xz并解压。
3. pip 安装以下 wheel 包：
• vllm‑0.8.2+xxx.whl
• flash_attn+xxx.whl （适配 vLLM 新加速 whl 包）
• ray‑2.43.0‑cp310‑cp310_${OS_Version}.whl
除了上述 wheel 包，其他依赖环境可以通过外部镜像源进行安装。安装过程中有其他依赖，需要提前配
置好 Python 的 pip 源。
7 MacaRT‑vLLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 50
AI 推理用户手册
7.3.1.3 配置环境变量
export MACA_PATH=your_maca_path
export PATH=${MACA_PATH}/bin:${MACA_PATH}/mxgpu_llvm/bin:${PATH}
export LD_LIBRARY_PATH=${MACA_PATH}/lib:${MACA_PATH}/ompi/lib:${MACA_PATH}/mxgpu_
,→llvm/lib:${LD_LIBRARY_PATH}
7.3.2 离线推理
离线推理代码示例如下：
from vllm import LLM, SamplingParams
# Sample prompts.
prompts = [
"Hello, my name is",
"The president of the United States is",
"The capital of France is",
"The future of AI is",
]
# Create a sampling params object.
sampling_params = SamplingParams(temperature=0.8, top_p=0.95)
# Create an LLM.
llm = LLM(model="facebook/opt-125m", tensor_parallel_size=1, dtype="float16", max_
,→model_len=2048)
# Generate texts from the prompts. The output is a list of RequestOutput objects
# that contain the prompt, generated text, and other information.
outputs = llm.generate(prompts, sampling_params)
# Print the outputs.
for output in outputs:
prompt = output.prompt
generated_text = output.outputs[0].text
print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")
其中主要配置为：
• LLM 初始化类：指定模型路径（可配置为本地路径，如果不是本地路径，会根据网络下载外网模型） 、
tensor 切分数量、模型数据类型（可不配置，如果没指定，将通过 model config 读取） 、模型最大处
理长度（可不配置，如果没设置，将从 model config 读取）
• SamplingParams：设置采样算法方式。参数配置可参照官方 vLLM‑0.8.2 版本进行配置。
7 MacaRT‑vLLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 51
AI 推理用户手册
7.3.3 吞吐测试
吞吐测试代码可参考官方 vLLm‑0.8.2 benchmark_throughput.py。
吞吐测试代码的运行方式示例 1：
python benchmark_throughput.py --model XXX --tensor-parallel-size 1 --num-prompts 
,→8 --trust-remote-code --input-len 1024 --output-len 512
模型为 XXX，tensor 并行为 1，8 条请求数量，信任模型路径的 tokenizer 方式，每条输入长度为 1024
个 token，输出为 512 个 token。
吞吐测试代码的运行方式示例 2：
python benchmark_throughput.py --model XXX --tensor-parallel-size 1 --num-prompts 
,→8 --trust-remote-code --dataset XXX.json
模型为 XXX，tensor 并行为 1，8 条请求数量，信任模型路径的 tokenizer 方式，通过从 dataset 选取语
料进行真实模拟。json 格式可参考ShareGPT_V3_unfiltered_cleaned_split.json。
运行程序后，结果打印如下：
Throughout: XXX request/s, XXXX token/s
打印结果指示每秒能接受多少请求，以及每秒处理的 token 数量（包括输入 token） 。
7.3.4 Server 服务
Server 请求服务参数设置可参考官方 vLLM‑0.8.2 版本：
API server 参数配置可参考api_server.py。
OpenAI server 参数配置可参考api_server.py。
参考示例如下：
python -m vllm.entrypoints.api_server --model XXX # 普 通server 方 式
python -m vllm.entrypoints.openai.api_server --model XXX --host localhost --chat-
,→template XXX.jinja ## openai 方 式 的 请 求
vllm server --model XXX
7 MacaRT‑vLLM 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 52
AI 推理用户手册
8 MacaRT‑vLLM‑metax
8.1 MacaRT‑vLLM‑metax介绍
vLLM‑metax 是专为沐曦通用 GPU 打造的 vLLM 框架后端插件，用于使 vLLM 推理框架能够在沐曦 GPU
上高效运行。当前兼容 vLLM v0.11.0 版本。
8.1.1 分支说明
已发布 vLLM‑metax 版本与 MXMACA 版本的映射关系，参见表 8.1。
表 8.1 vLLM‑metax、vLLM 官方、PyTorch 的版本映射关系
vLLM‑metax vLLM PyTorch
v0.10.2 v0.10.2 2.6
v0.11.0 v0.11.0 2.6
v0.11.2 v0.11.2 2.8
v0.12.0 v0.12.0 2.8
v0.13.0 v0.13.0 2.8
v0.14.0 v0.14.0 2.8
v0.15.0 v0.15.0 2.8
8.2 MacaRT‑vLLM‑metax功能与局限性
MacaRT‑vLLM‑metax 兼容适配了 vLLM v0.11.0 版本，包含了以下功能和特性，以及局限性：
功能和特性：
• 兼容 vLLM v0.11.0 支持的所有模型 BFLOAT16 推理和部分模型 FLOAT16 推理，支持官方多模态模型
• 兼容原生 LLM、Engine、Kernel 的 API 接口
• 兼容原生 server 和 OpenAI server 接口
• 支持 Lora 特性
• 支持 GPTQ 和 AWQ 量化方式
• 支持 ray 和 mp 方式启动单机多卡推理；设置 --distributed-executor-backend 可以指定不同
后端进行多卡推理，默认使用 ray
• 支持 prefix_cache 方式
8 MacaRT‑vLLM‑metax 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 53
AI 推理用户手册
• 支持 enforce_eager=False 方式。需通过显式配置，默认为True。另外，需要额外设置 MACA 环
境变量来获取加速效果：export MACA_GRAPH_LAUNCH_MODE=1
局限性：
• 不支持 FP8 类型 KV Cache 和相关 FP8 模型
• 包含 Ubuntu 20、Ubuntu 22、kylin2309a 系统版本，后续完善支持其他系统
8.3 MacaRT‑vLLM‑metax使用流程
本章节介绍 MacaRT‑vLLM‑metax 的安装和使用步骤，功能主要分为离线推理、吞吐测试和 Sever 服务。
8.3.1 环境准备
使用 MacaRT‑vLLM‑metax 进行推理需要准备好环境。目前提供两种方式：镜像和 wheel 包。如果您想
开发、调试或测试 vLLM‑metax 的最新功能，可以从源码构建 vLLM‑metax 并将其安装到 Docker 环境
中。vLLM‑metax 源码构建请参考：MacaRT‑vLLM‑metax 源码构建。
8.3.1.1 使用 vLLM 镜像
从沐曦开发者中心的镜像资源中心获取镜像。
选择合适的架构类型、操作系统类型、Python 版本后，点击 docker 命令复制，获取此 Docker 镜像的
拉取命令。
创建容器环境示例如下：
export IMAGE=cr.metax-tech.com/public-ai-release/maca/vllm-metax:0.15.0-maca.ai3.5.
,→3.203-torch2.8-py310-ubuntu22.04-amd64
sudo docker run -it --privileged --cap-add=SYS_PTRACE --security-opt 
,→seccomp=unconfined \
--device=/dev/dri --device=/dev/mxcd --device=infiniband --group-add video --
,→name vllm_metax --network=host \
--security-opt apparmor=unconfined --shm-size '100gb' --ulimit memlock=-1 \
-v /mnt:/mnt \
$IMAGE \
/bin/bash
sudo docker exec -it vllm_metax /bin/bash
8 MacaRT‑vLLM‑metax 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 54
AI 推理用户手册
8.3.1.2 安装 wheel 包
操作步骤
1. 预先安装沐曦平台的 torch、flash attn、mcoplib、xformer（可选）环境。
2. 获 取 MacaRT‑vLLM 压 缩 包 maca‑vllm‑metax‑0.11.0‑py310‑xxx‑${OS_Version}.tar .xz并 解
压。
3. pip 安装以下 wheel 包：
• vllm_metax‑0.11.0+xxx.whl
• flash_attn+xxx.whl （适配 vLLM 新加速 whl 包）
• ray‑2.48.0‑cp310‑cp310_${OS_Version}.whl
• mcoplib‑0.1.0‑+macaxxx‑cp310‑cp310_${OS_Version}.whl
• vllm‑0.11.0‑cp310‑xxx_${OS_Version}.whl
4. vLLM‑metax、vLLM、mcoplib 安装后需要手动执行 mcoplib_init 命令。
除了上述 wheel 包，其他依赖环境可以通过外部镜像源进行安装。安装过程中有其他依赖，需要提前配
置好 Python 的 pip 源。
8.3.1.3 源代码构建教程
从沐曦开发者社区 中获取 vLLM 镜像并启动，参见《沐曦通用 GPU 用户指南》中“容器相关场景支持”
章节。
8.3.1.4 设置环境变量
# setup MACA path
export MACA_PATH="/opt/maca"
# cu-bridge
export CUCC_PATH="${MACA_PATH}/tools/cu-bridge"
export CUDA_PATH=/root/cu-bridge/CUDA_DIR
export CUCC_CMAKE_ENTRY=2
# update PATH
export PATH=${MACA_PATH}/mxgpu_llvm/bin:${MACA_PATH}/bin:${CUCC_PATH}/tools:${CUCC_
,→PATH}/bin:${PATH}
export LD_LIBRARY_PATH=${MACA_PATH}/lib:${MACA_PATH}/ompi/lib:${MACA_PATH}/mxgpu_
,→llvm/lib:${LD_LIBRARY_PATH}
export VLLM_INSTALL_PUNICA_KERNELS=1
8 MacaRT‑vLLM‑metax 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 55
AI 推理用户手册
8.3.1.5 构建 vLLM
克隆 vLLM 项目：
git clone --depth 1 --branch v0.11.0 https://github.com/vllm-project/vllm
cd vllm
构建官方版本 vLLM：
python use_existing_torch.py
pip install -r requirements/build.txt
VLLM_TARGET_DEVICE=empty pip install -v . --no-build-isolation
8.3.1.6 构建 vLLM‑metax
安装所需组件：
python use_existing_metax.py
pip install -r requirements/build.txt
安装 vLLM：
pip install . -v --no-build-isolation
如果想要开发 vLLM，请以可编辑模式安装：
pip install -e . -v --no-build-isolation
（可选）构建可移植的 wheel 包：
python -m build -w -n
pip install dist/*.whl
8.3.2 离线推理
离线推理代码示例如下：
from vllm import LLM, SamplingParams
# Sample prompts.
prompts = [
"Hello, my name is",
"The president of the United States is",
"The capital of France is",
"The future of AI is",
]
# Create a sampling params object.
(下页继续)
8 MacaRT‑vLLM‑metax 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 56
AI 推理用户手册
(续上页)
sampling_params = SamplingParams(temperature=0.8, top_p=0.95)
def main():
# Create an LLM.
llm = LLM(model="facebook/opt-125m")
# Generate texts from the prompts.
# The output is a list of RequestOutput objects
# that contain the prompt, generated text, and other information.
outputs = llm.generate(prompts, sampling_params)
# Print the outputs.
print("\nGenerated Outputs:\n" + "-" * 60)
for output in outputs:
prompt = output.prompt
generated_text = output.outputs[0].text
print(f"Prompt: {prompt!r}" )
print(f"Output: {generated_text!r}" )
print("-" * 60)
if __name__ == "__main__":
main()
其中主要配置为：
• LLM 初始化类：指定模型路径（可配置为本地路径，如果不是本地路径，会根据网络下载外网模型） 、
tensor 切分数量、模型数据类型（可不配置，如果没指定，将通过model config 读取） 、模型最大处
理长度（可不配置，如果没设置，将从 model config 读取）
• SamplingParams：设置采样算法方式。参数配置可参照官方 vLLM v0.11.0 版本进行配置。
8.3.3 吞吐测试
吞吐测试代码可参考官方 vLLm‑0.11.0 benchmark_throughput.py。
吞吐测试代码的运行方式示例 1：
python -m vllm.entrypoints.cli.main bench throughput --model XXX --tensor-parallel-
,→size 1 --num-prompts 8 --trust-remote-code --input-len 1024 --output-len 512
模型为 XXX，tensor 并行为 1，8 条请求数量，信任模型路径的 tokenizer 方式，每条输入长度为 1024
个 token，输出为 512 个 token。
吞吐测试代码的运行方式示例 2：
vllm bench throughput --model XXX --tensor-parallel-size 1 --num-prompts 8 --trust-
,→remote-code --dataset XXX.json
8 MacaRT‑vLLM‑metax 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 57
AI 推理用户手册
模型为 XXX，tensor 并行为 1，8 条请求数量，信任模型路径的 tokenizer 方式，通过从 dataset 选取语
料进行真实模拟。json 格式可参考ShareGPT_V3_unfiltered_cleaned_split.json。
运行程序后，结果打印如下：
Throughout: XXX request/s, XXXX token/s
打印结果指示每秒能接受多少请求，以及每秒处理的 token 数量（包括输入 token） 。
8.3.4 Server 服务
Server 请求服务参数设置可参考官方 vLLM‑0.11.0 版本：
API server 参数配置可参考api_server.py。
OpenAI server 参数配置可参考api_server.py。
参考示例如下：
python -m vllm.entrypoints.api_server --model XXX # 普 通server 方 式
python -m vllm.entrypoints.openai.api_server --model XXX --host localhost --chat-
,→template XXX.jinja ## openai 方 式 的 请 求
vllm server --model XXX
8 MacaRT‑vLLM‑metax 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 58
AI 推理用户手册
9 MacaRT‑ModelZoo
9.1 MacaRT‑ModelZoo 介绍
MacaRT‑ModelZoo 方便用户在沐曦通用 GPU 上快速部署验证深度学习模型，提供多种常见模型在沐曦
通用 GPU 上的部署方案，应用于图片分类、物体检测、语义分割、超分辨率、行为识别、关键点检测、
字符识别、语音识别、推荐系统、多模态、自然语言处理、图生成等场景。具有如下特性：
• 丰富的应用场景，涵盖大部分主流网络模型，可使用现有或增加同类模型快速部署验证
• 易用的运行环境，提供的 Docker 镜像具有完备的 MacaRT‑ModelZoo 模型部署软件栈
• 完整的数据链路，包含数据预处理、模型推理、后处理及结果指标评估等模块的实现
• 便捷的模型评估，通过命令参数可评估不同模型在多种精度下的模型精度和性能
• 统一的参数配置，从规范化的配置文件中获取模型部署量化、预处理与后处理等参数
9.2 模型评测条件
MacaRT‑ModelZoo 上快速实现模型部署的依赖条件如下所示：
• 安装有沐曦通用 GPU 板卡及完整运行时软件栈的主机
• modelzoo.cnn.inference 的 Release Docker 镜像软件包
• ONNX 格式的模型文件和带有标注信息的数据集
9.3 代码目录结构及说明
MacaRT‑ModelZoo 的目录结构和说明如下（以 classification 类别中 Resnet18 模型评测展开） ：
├── _base（ 模 型 评 测 基 类 代 码 ）
├── classification（ 图 像 分 类 类 ）
├── code （ 模 型 评 测 代 码 ）
├── data （ 模 型 评 测 数 据 集 ， 软 链 接 到 实 际 数 据 集 目 录 ）
├── models（ 模 型 配 置 集 合 ）
├── ox_resnet18_224x224 （ 模 型 配 置 目 录 ）
├── config.yaml（ 模 型 评 测 配 置 参 数 ）
└── performance.json（ 模 型 标 准 的 精 度 和 性 能 指 标 ）
└── readme.md （ 模 型 评 测 说 明 ， 注 意 每 个 模 型 类 别 的 此 文 件 ， 可 能 有 特 殊 说 明 ）
├── action2 （ 行 为 识 别 类 ）
├── Autoregressive（ 语 音 处 理 类 ）
├── CTR（ 推 荐 系 统 类 ）
├── detection（ 物 体 检 测 类 ）
(下页继续)
9 MacaRT‑ModelZoo 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 59
AI 推理用户手册
(续上页)
├── face_recognition（ 人 脸 识 别 类 ）
├── landmark （ 关 键 点 检 测 类 ）
├── multimodal（ 多 模 态 类 ）
├── NLP_Transformer（ 自 然 语 言 处 理 类 ）
├── OCR（ 字 符 识 别 类 ）
├── segmentation（ 语 义 分 割 类 ）
├── stable_diffusion（ 图 生 成 类 ）
└── video_enhancement（ 超 分 辨 率 类 ）
9.4 源码、模型和数据集
9.4.1 源码镜像获取
可通过沐曦软件中心获取 MacaRT‑ModelZoo 源代码的镜像和模型。
操作步骤
1. 进入软件中心，点击 Docker 的子页面。
2. 选择沐曦通用 GPU 的型号、发布版本号。
3. 点击 AI 查看 MACARTAI 相关的 Docker 镜像。
4. 软件包类型选择 modelzoo.cnn.inference，架构类型选择 amd64 或 arm64，操作系统类型选择
CentOS 或 Ubuntu 等。
通过上述操作选择 MacaRT‑ModelZoo 源代码的镜像，点击 docker 命令复制，获取此 Docker 镜像的
拉取命令，可通过此命令在沐曦软件中心服务器上拉取此镜像。
进入容器，可在/workspace/modelzoo/MACA_AI_CNN 目录查看 MacaRT‑ModelZoo 源代码，此容
器除了包含 MacaRT‑ModelZoo 源码，还包含完整的 MacaRT‑ModelZoo 运行时软件栈，可大大减少用
户在搭建运行环境所耗费的时间。容器镜像的使用，参见《沐曦通用 GPU 用户指南》中“容器相关场景
支持”章节。
9.4.2 模型获取
MacaRT‑ModelZoo 可评测的模型会陆续更新到 沐曦软件中心，进入软件中心后点击 Model 的子页面，
可根据模型类别和模型名称，点击下载得到模型。
用户也可以使用公开模型或私有模型进行评测，如果被测评的模型预处理、后处理和指标评估与这一类
别中其他的不一致，则需要修改 MacaRT‑ModelZoo 代码和配置文件对其支持。此外，模型评测的成功
与否还取决于 MacaRT 对模型的支持能力，遇到不支持的算子可以联系沐曦技术支持工程师在 MacaRT
上增加算子，也可以添加 MacaRT 自定义算子，操作步骤参见 3.5 自定义算子。
9 MacaRT‑ModelZoo 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 60
AI 推理用户手册
9.4.3 数据集获取
MacaRT‑ModelZoo 中模型的量化和结果指标评估需要数据集，有以下三种获取方式：
• 联系沐曦技术支持工程师，获取数据集，无需修改直接使用
• 下载公开数据集，可能需要调整
• 自己制作数据集，可能需要调整
需要调整的原因是：可能存在数据集的数据存放目录结构和标注信息与 MacaRT‑ModelZoo 中要求的数
据集有所差异。
9.5 模型评测步骤
9.5.1 启动容器镜像
从发布的软件包中获取 modelzoo.cnn.inference 容器镜像并启动， 此容器镜像包含 MacaRT‑ModelZoo
模型评测所需的运行时软件栈。容器镜像的使用，参见《沐曦通用 GPU 用户指南》中“容器相关场景支
持”章节。容器镜像启动时需要挂载用户的 ONNX 模型目录和数据集目录。
9.5.2 建立数据集的关联
参见 9.4.3 数据集获取，准备好数据集后，切换到模型大类目录下建立软链接。例如，测试 Resnet18 可
执行以下命令：
cd $MODELZOO_PATH/classification
ln -s $CLASSIFICATION_DATA_SET_PATH data
9.5.3 执行模型评测
MacaRT‑ModelZoo 中评测模型性能或精度，需要先切换到模型大类目录，然后统一使用以下命令：
python ./code/OnnxRT_v2/start.py $modelpath $batchsize $precision $task $modelfile
,→$ep $num_thr
通过参数可以配置测试任务为性能测试任务、精度测试任务或两者兼有，也可以配置测试精度为 int8、
fp16 或 fp32，具体参数说明参见表 9.1：
表 9.1 模型评测命令行参数解析
参数名称 说明
modelpath 模型配置目录，运行 resnet18 则是 models/ox_resnet18_224x224
batchsize 推理 batchsize
下页继续
9 MacaRT‑ModelZoo 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 61
AI 推理用户手册
表 9.1 – 续上页
参数名称 说明
precision 推理精度类型，目前支持 fp32、fp16、int8
task 测试任务，normal 测试模型精度和 fps；fpsonly 只测试模型 fps；fpsclosed
只测试模型精度
modelfile 模型路径，若为./，会默认读取 config 配置的模型路径
ep 推理运行的后端平台，默认为 maca，即沐曦通用 GPU 平台，可选 CPU 平台
num_thr 测试的线程数，建议数值为 1 或者 8 的倍数
9 MacaRT‑ModelZoo 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 62
AI 推理用户手册
10 MacaRT‑LMDeploy
10.1 MacaRT‑LMDeploy 介绍
MacaRT‑LMDeploy 是 在 沐 曦 通 用 GPU 上 适 配 官 方 LMDeploy 的 推 理 工 具， 基 于 MXMACA 后 端 对
LMDeploy 方法进行了兼容适配和 Kernel 优化。使用 MacaRT‑LMDeploy 在沐曦通用 GPU 上进行大模
型推理，其方法和功能与官方 LMDeploy 兼容。
10.2 MacaRT‑LMDeploy 功能与局限性
MacaRT‑LMDeploy 兼容适配了最新 LMDeploy，除以下局限性以外，兼容其他所有 LMDeploy 原有功
能，包括离线批处理、在线推理、控制台命令行交互等，可参考LMDeploy 官方文档。
局限性：
• 支持 PyTorch 推理后端，不支持 TurboMind 引擎
• 支持 FLOAT16 和 BFLOAT16 推理，暂不支持量化模型部署
• 当前只对 Qwen2.5，InternLM 等部分模型进行了功能验证和性能优化
• 处于性能考虑，block_size 只支持 8、16、32，建议 16
• 当前仅包含 Ubuntu 20 和 Ubuntu 22 系统版本，后续完善支持其他系统
10.3 MacaRT‑LMDeploy 使用流程
本章节介绍 MacaRT‑LMDeploy 的使用步骤，主要分为离线推理、静态推理性能测试和 Server 服务动态
推理性能测试。
10.3.1 环境准备
使用 MacaRT‑LMDeploy 进行推理需要以下准备：
• 获取 vLLM 镜像
• 安装 dlinfer
• 安装 lmdeploy
注解: 完成上述步骤后，LMDeploy 本身的依赖已经完整，但是在运行具体模型时，某些模型可能
有它自己独有的依赖，请按照相关提示进行安装，提前配置好 Python 的 pip 源。
10 MacaRT‑LMDeploy 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 63
AI 推理用户手册
10.3.1.1 获取 vLLM 镜像
从发布的软件包中获取 vLLM 镜像并启动，参见《沐曦通用 GPU 用户指南》中“容器相关场景支持”章
节。
10.3.1.2 安装 dlinfer
1. dlinfer 编译需要 CUDA toolkit，建议使用CUDA 11.6。 可以在启动容器时通过/usr/local:/usr/
local -v 挂载宿主机的 /usr/local/cuda 路径到容器。
2. 设置 MACA 环境变量：
DEFAULT_DIR="/opt/maca"
export MACA_PATH=${1:-$DEFAULT_DIR}
export CUDA_PATH=/usr/local/cuda
export CUCC_PATH=${MACA_PATH}/tools/cu-bridge
export PATH=${CUDA_PATH}/bin:${MACA_PATH}/mxgpu_llvm/bin:${MACA_PATH}/bin:${CUCC_
,→PATH}/tools:${CUCC_PATH}/bin:$PATH
export LD_LIBRARY_PATH=${MACA_PATH}/lib:${MACA_PATH}/ompi/lib:${MACA_PATH}/mxgpu_
,→llvm/lib:${LD_LIBRARY_PATH}
3. 源码安装：
git clone https://github.com/DeepLink-org/dlinfer.git
cd dlinfer
# 建 议 使 用 以 下commit ， 已 经 过 测 试
git checkout dbb1feb71b0983d8b5b166771a7bb99e00461b36
rm -rf _skbuild
pip3 install -r requirements/maca/full.txt
DEVICE=maca python3 setup.py develop
10.3.1.3 安装 LMDeploy
源码安装：
git clone https://github.com/InternLM/lmdeploy.git
cd lmdeploy
# 建 议 使 用 以 下commit ， 已 经 过 测 试
git checkout 832bfc45b4497e8d16e08ecfd663671e634aae40
LMDEPLOY_TARGET_DEVICE=maca python setup.py develop
10 MacaRT‑LMDeploy 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 64
AI 推理用户手册
10.3.2 离线推理
离线推理代码示例如下：
import lmdeploy
from lmdeploy import PytorchEngineConfig
if __name__ == "__main__":
pipe = lmdeploy.pipeline("internlm/internlm2-chat-7b",
backend_config = PytorchEngineConfig(tp=1,
cache_max_entry_count=0.8, device_type="maca", block_
,→size=16))
question = ["Shanghai is", "Please introduce China", "How are you?"]
response = pipe(question, request_output_len=256, do_preprocess=False)
for idx, r in enumerate(response):
print(f"Q: {question[idx]}")
print(f"A: {r.text}")
print()
API 基本用法请参考官方文档。
10.3.3 静态推理性能测试
因为 profile_generation.py 目前不支持传入 device_type，需要手动修改代码如下：
--- a/benchmark/profile_generation.py
+++ b/benchmark/profile_generation.py
@@ -430,6 +430,7 @@ def main():
eager_mode=args.eager_mode,
enable_prefix_caching=args.enable_prefix_caching,
dtype=args.dtype,
+ device_type='maca',
)
测试代码：
python profile_generation.py /models/llm/Internlm2-chat-7b --backend pytorch -c 1 -
,→pt 256 -ct 128 --tp 1 --cache-block-seq-len 16 --dtype float16
• python profile_generation.py ：脚本在 lmdeploy/benchmark。
• /models/llm/Internlm2-chat-7b ：模型文件路径。
• --backend pytorch ：指定使用的后端为 PyTorch。
• -c 1 ：并发数为 1。
• -pt 256 ：输入长度为 256。
• -ct 128 ：输出长度为 128。
• --tp 1 ：设置张量并行的大小为 1。
10 MacaRT‑LMDeploy 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 65
AI 推理用户手册
• --cache-block-seq-len 16 ：设置 block size 为 16。
• --dtype float16 ：指定数据类型为 float16。
运行程序后，结果打印如下：
-------------------------------------
total time: 5.51s
concurrency: 1, test_round: 3
input_tokens: 256, output_tokens: 128
first_token latency(min, max, ave): 0.045s, 0.047s, 0.046s
total_token latency(min, max, ave): 1.833s, 1.846s, 1.839s
token_latency percentiles(50%,75%,95%,99%)(s):[0.014, 0.014, 0.02, 0.021]
throughput(output): 69.68 token/s
throughput(total): 209.04 token/s
--------------------------------------
打印结果指示首字延迟、输出吞吐和全部吞吐（包括首个 token） 。
10.3.4 Server 服务动态推理性能测试
详细信息可参考官方文档请求吞吐量性能测试和api_server 性能测试。
启动服务
启动服务代码示例：
lmdeploy serve api_server --server-port 23333 --tp 1 --backend pytorch --max-batch-
,→size 256 /models/llm/Internlm2-chat-7b --dtype float16 --device maca --cache-
,→block-seq-len 16
输出如下：
HINT: Please open http://0.0.0.0:23333 in a browser for detailed api usage!!!
HINT: Started server process[1384373]
HINT: Waiting for application startup.
HINT: Application startup complete.
HINT: Uvicorn running on http://0.0.0.0:23333 (Press CTRL+C to quit)
发起吞吐测试请求
1. profile_restful_api.py 偶发 NaN 异常，为了暂时规避该问题，请手动修改代码如下：
--- a/benchmark/profile_restful_api.py
+++ b/benchmark/profile_restful_api.py
@@ -153,7 +153,7 @@ async def async_request_openai_completions(
payload = {
'model': request_func_input.model,
'prompt': prompt,
- 'temperature': 0.0,
(下页继续)
10 MacaRT‑LMDeploy 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 66
AI 推理用户手册
(续上页)
+ 'temperature': 1.0,
'best_of': 1,
'max_tokens': request_func_input.output_len,
'stream': not args.disable_stream,
2. 下载ShareGPT_V3_unfiltered_cleaned_split.json：
python profile_restful_api.py --port 23333 --backend lmdeploy --dataset-path ./
,→ShareGPT_V3_unfiltered_cleaned_split.json
输出如下:
Backend: lmdeploy
Traffic request rate: inf
Successful requests: 1000
Benchmark duration(s): 96.23
Total input tokens: 228316
Total generated tokens: 195534
Total generated tokens (retokimized): 181775
Request throughput (req/s): 10.39
Input token throughput (tok/s): 2372.62
Output token throughput (tok/s): 2031.95
End-to-End Latency
Mean E2E Latency (ms): 43531.86
Median E2E Latency (ms): 42845.51
Mean TTFT (ms): 26513.87
Median TTFT (ms): 24519.39
P99 TTFT (ms): 62724.06
Time per Output Token (excl. 1st token)
Mean TPOT (ms): 110.65
Median TPOT (ms): 95.38
P99 TPOT (ms): 535.69
Inter-token Latency
Mean ITL (ms): 91.67
Median ITL (ms): 61.98
P99 ITL (ms): 724.82
10 MacaRT‑LMDeploy 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 67
AI 推理用户手册
11 Diffusers
沐曦通用 GPU 完全支持官方 Diffusers 推理工具，直接通过 pip install diffusers==0.31.0 安
装即可，具体使用方法请参考官方使用文档。
11 Diffusers 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 68
AI 推理用户手册
12 Transformers
沐曦通用 GPU 完全支持官方 Transformers 推理工具，直接通过 pip install transformers==4.
46.3 安装即可，具体使用方法请参考官方使用文档。
12 Transformers 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 69
AI 推理用户手册
13 MacaRT‑SGLang
13.1 MacaRT‑SGLang 介绍
MacaRT‑SGLang 是在沐曦通用 GPU 上适配官方 SGLang 的推理工具，基于 MXMACA 后端对 SGLang
方法进行了兼容适配和 Kernel 优化。使用 MacaRT‑SGLang 在沐曦通用 GPU 上进行大模型推理，其方
法和功能与官方 SGLang 兼容。当前兼容版本为 SGLang 0.4.3，PyTorch 要求为 2.4。
13.2 MacaRT‑SGLang 功能
支 持 的 模 型 包 括：DeepSeek‑R1‑BF16、DeepSeek‑R1‑W8A8 和 DeepSeek‑R1‑Distill‑Qwen‑1.5B。
DeepSeek‑R1‑W8A8 模型是采用 compress‑tensor 的 W8A8‑INT8 量化方式量化而来。
13.3 MacaRT‑SGLang 使用流程
本章节介绍 MacaRT‑SGLang 的使用步骤，主要分为在线推理、吞吐测试和精度测试。
13.3.1 环境准备
使用 MacaRT‑SGLang 进行推理需要准备好环境。目前仅提供镜像方式。
13.3.1.1 使用 SGLang 镜像
从发布的软件包中获取 SGLang 镜像并启动，参见《沐曦通用 GPU 用户指南》中“容器相关场景支持”
章节。
13.3.1.2 设置环境变量
单机场景下，仅需在一台机器的容器内执行操作；多机场景时，需在所有容器中分别执行一次。
export MACA_SMALL_PAGESIZE_ENABLE=1
多机场景下，还需设置以下环境变量：
export GLOO_SOCKET_IFNAME=网 口 名
对于 GLOO_SOCKET_IFNAME 环境变量，需在宿主机上执行 ifconfig-a 指令获取与该宿主机 IP 地址
对应的网口。
13 MacaRT‑SGLang 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 70
AI 推理用户手册
13.3.1.3 启动 Server
• 对于 DeepSeek‑R1‑BF16 全量模型，以 4 机 32 卡为例：
当前运行建议按照张量并行（tp）方式切分为 32 份。
python3 -m sglang.launch_server --model-path XXX --tp 32 --dist-init-addr 100.79.
,→153.153:5000 --nnodes 4 --node-rank 0 --disable-cuda-graph
– --tp 32 表示 tp 并行的切分数量为 32
– --model-path XXX 指定模型存放路径
– --dist-init-addr 100.79.153.153:5000 指定主节点的 IP 和端口号（可默认为 5000） ，其
他三个节点和主节点保持一致
– --nnodes 4 表示节点数量
– --node-rank 0 表示当前机器所属的节点索引 0。需要注意的是必须先启动主节点，然后才能启
动其他节点
• 对于 DeepSeek‑R1‑W8A8 量化模型，使用 16 卡即可运行。以 2 机 16 卡为例：
该模型需要根据沐曦发布的文档自行量化，可参考相关推理部署手册中“W8A8 模型转换”章节。
当前运行建议按照 tp 方式切分为 16 份。
python3 -m sglang.launch_server --model-path XXX --tp 16 --dist-init-addr 100.79.
,→153.153:5000 --nnodes 2 --node-rank 0 --disable-cuda-graph
• 对于 DeepSeek‑R1‑Distil‑Qwen‑1.5B 模型，使用单卡即可运行。以单卡为例:
python3 -m sglang.launch_server --model-path ${Model_path} --tp 1 --trust-remote-
,→code --disable-cuda-graph
13.3.2 在线推理
待端口顺利启动后，向 Sever 发送请求即可（另起终端） 。以下示例简单验证推理服务。
import requests
url = "http://localhost:30000/generate"
data = {"text": "What is the capital of France?"}
response = requests.post(url, json=data)
print(response.json())
13 MacaRT‑SGLang 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 71
AI 推理用户手册
13.3.3 吞吐测试
python3 -m sglang.bench_serving --backend sglang --dataset-name random m --random-
,→input-len ${input-len} --random-output-len ${output-len} --random-range-ratio 1.
,→0 --dataset-path ./dataset/ShareGPT_V3_unfiltered_cleaned_split.json --num-
,→prompt ${batch_size}
• ${input-len} 表示输入长度
• ${output-len} 表示输出长度
• ${batch_size} 指定输入批次数量
13.3.4 精度测试
13.3.4.1 MMLU 精度测试
如果使用 MMLU 数据集进行精度测试， 需要准备 data 数据。 下载data.tar文件， 解压并拷贝至dataset
路径。
此外，如果机器无法访问外网，还需要下载 cl100k_base.tiktoken文件，放入容器内任意位置。
1. 安装依赖。
pip install blobfile
export TIKTOKEN_CACHE_DIR=${path}
${path} 表示 cl100k_base.tiktoken文件所在的路径，不需要包含文件名。
2. 执行 bench_sglang.py 进行精度测试，使用的测试命令行如下：
python code/bench_sglang.py --nsub 10 --data_dir ./dataset/data
--nsub 指定测试问题的数量，最多为 60。如不指定，默认是 60。
13.3.4.2 C‑Eval 精度测试
1. 安装依赖。
pip install eval-type-backport
2. 执行 run_ceval_client.py 进行精度测试，使用的测试命令行如下：
python code/run_ceval_client.py --model ${Model_path} --test_jsonl ./dataset/
,→ceval_val_cmcc.jsonl --batch_size 64
• -model ${Model_path} 为 model 所在的路径。
• --test_jsonl ./dataset/ceval_val_cmcc.json1 为 C‑Eval 数据集的路径。
13 MacaRT‑SGLang 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 72
AI 推理用户手册
该脚本对接的 Server 端口号为 8000，所以需要在启动 SGLang Server 时加上 --port 8000，示例如
下:
python -m sglang.launch_server --model ${Model_path} --tp 32 --dist-init-addr 100.
,→79.153.153:5000 --nnodes 4 --node-rank 0 --trust-remote-code --isable-cuda-graph 
,→--port 8000
13 MacaRT‑SGLang 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 73
AI 推理用户手册
14 附录
14.1 术语/缩略语
术语/缩略语 全称 说明
Batch 全部样本里的一批数据
BFC Best‑Fit with Coalescing 一种内存管理策略
CpuEP CPU Execution Provider 以 CPU 作为 ONNX Runtime 的后端进行模
型推理
LLM Large Language Model 大语言模型
MacaConverter 沐曦研发，将训练的模型转换为 ONNX 模型
的工具
MacaEP MXMACA Execution Provider 以沐曦通用 GPU 作为 ONNX Runtime 的后
端进行模型推理
MacaPrecision 沐曦研发，精度对比工具
MacaQuantizer 沐曦研发，模型量化工具
MacaRT MXMACA Runtime 沐曦研发，沐曦通用 GPU 的推理引擎
ModelZoo 模型库
ONNX Open Neural Network Exchange 开放神经网络交换，表示深度学习模型的开
放格式，可将训练好的模型存储为此格式
ONNX Runtime 一个开源的跨平台推理框架
OpenPPL‑LLM OpenPPL 推出的大语言模型（LLM）推理引
擎
PMX PPL Model Exchage OpenPPL 模型转换工具
Tensor 张量，是一种特殊的数据结构
14 附录 沐曦股份专有信息 OG‑23025‑020‑F5_V20 | 74
